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Note 
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About  this  Book 


The  Presentation  Manager  Programming  Reference  is  a detailed  technical  reference,  in  three 
volumes,  for  application  programmers  creating  programs  using  the  Presentation  Manager  interface. 

Chapter  1 contains  important  information.  You  should  read  it  before  using  this  book. 

This  reference  does  not  give  guidance  on  how  to  use  the  functions,  nor  does  it  contain  information 
about  how  the  functions  are  related  to  each  other.  It  is  intended  to  be  used  in  conjunction  with  the 
Programming  Guide  Volumes  II  and  III. 


Prerequisite  Knowledge 

The  OS/2  2.0  Technical  Library  is  intended  for  professional  application  developers  knowledgeable  in 
at  least  one  programming  language  in  which  OS/2  programs  can  be  written.  The  information  in  the 
Technical  Library  assumes  that  you  are  new  to  programming  with  OS/2  and  the  Presentation 
Manager.  You  should  understand  the  OS/2  services  available  to  users. 


Related  Publications 

The  Application  Design  Guide  and  the  Programming  Guide  Volumes  I,  II,  and  III  introduce  the 
programming  concepts  that  you  should  understand  before  you  begin  developing  applications  to  run 
on  the  OS/2  operating  system.  Getting  Started  describes  the  online  programming  books,  tools, 
programming  aids,  and  sample  programs  that  make  up  the  IBM  Developer's  Toolkit  for  OS/2  2.0. 


Organization  of  this  Book 

This  book  is  in  three  volumes.  The  contents  of  each  volume  are  as  follows: 

Volume  I (Functions) 

Chapter  1,  “Introduction”  on  page  1-1 

You  should  read  this  chapter  before  using  this  book. 

Chapter  2,  “Device  Functions”  on  page  2-1 

Chapter  3,  “Direct  Manipulation  Functions”  on  page  3-1 

Chapter  4,  “Dynamic  Data  Formatting  Functions”  on  page  4-1 

Chapter  5,  “Graphics  Functions”  on  page  5-1 

Chapter  6,  “Profile  Functions”  on  page  6-1 

Chapter  7,  “Spooler  Functions”  on  page  7-1 

Volume  II  (Functions  and  Workplace) 

Chapter  8,  “Window  Functions”  on  page  8-1 

Chapter  9,  “Workplace  Classes,  Instance  Methods,  and  Class  Methods”  on  page  9-1 
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Volume  III  (Related  Information  and  Data  Types) 

Chapter  10,  “Functions  Supplied  by  Applications”  on  page  10-1 

Chapter  11,  “Introduction  to  Message  Processing”  on  page  11-1 

Chapter  12,  “Default  Window  Procedure  Message  Processing”  on  page  12-1 

Chapter  13,  “Button  Control  Window  Processing”  on  page  13-1 

Chapter  14,  “Entry  Field  Control  Window  Processing”  on  page  14-1 

Chapter  15,  “Frame  Control  Window  Processing”  on  page  15-1 

Chapter  16,  “List  Box  Control  Window  Processing”  on  page  16-1 

Chapter  17,  “Menu  Control  Window  Processing”  on  page  17-1 

Chapter  18,  “Multi-Line  Entry  Field  Control  Window  Processing”  on  page  18-1 

Chapter  19,  “Prompted  Entry  Field  Control  Window  Processing”  on  page  19-1 

Chapter  20,  “Scroll  Bar  Control  Window  Processing”  on  page  20-1 

Chapter  21,  “Spin  Button  Control  Window  Processing”  on  page  21-1 

Chapter  22,  “Static  Control  Window  Processing”  on  page  22-1 

Chapter  23,  “Title  Bar  Control  Window  Processing”  on  page  23-1 

Chapter  24,  “Container  Control  Window  Processing”  on  page  24-1 

Chapter  25,  “Notebook  Control  Window  Processing”  on  page  25-1 

Chapter  26,  “Slider  Control  Window  Processing”  on  page  26-1 

Chapter  27,  “Value  Set  Control  Window  Processing”  on  page  27-1 

Chapter  28,  “Clipboard  Messages”  on  page  28-1 

Chapter  29,  “Direct  Manipulation  (Drag)  Messages”  on  page  29-1 

Chapter  30,  “Dynamic  Data  Exchange  Messages”  on  page  30-1 

Chapter  31,  “Help  Manager  Messages”  on  page  31-1 

Chapter  32,  “Resource  Flies”  on  page  32-1 

Chapter  33,  “Graphics  Orders”  on  page  33-1 
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Chapter  34,  “Code  Pages”  on  page  34-1 


Appendix  A,  “Data  Types”  on  page  A-1 
Appendix  B,  “Error  Codes”  on  page  B-1 
Appendix  C,  “Error  Explanations”  on  page  C-1 
Appendix  D,  “Standard  Bit-Map  Formats”  on  page  D-1 
Appendix  E,  “Fonts  Supplied  with  OS/2”  on  page  E-1 
Appendix  F,  “The  Font-File  Format”  on  page  F-1 
Appendix  G,  “Format  of  Interchange  Files”  on  page  G-1 
Appendix  H,  “Initialization  File  Information”  on  page  H-1 
Appendix  I,  “Virtual  Key  Definitions”  on  page  1-1 
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Notices 


References  in  this  publication  to  IBM  products,  programs,  or  services  do  not  imply  that  IBM  intends 
to  make  these  available  in  all  countries  in  which  IBM  operates.  Any  reference  to  an  IBM  product, 
program  or  service  is  not  intended  to  state  or  imply  that  only  IBM's  product,  program,  or  service  may 
be  used.  Any  functionally  equivalent  product,  program,  or  service  that  does  not  infringe  any  of  IBM's 
intellectual  property  rights  or  other  legally  protectible  rights  may  be  used  instead  of  the  IBM  product, 
program,  or  service.  Evaluation  and  verification  of  operation  in  conjunction  with  other  products, 
programs,  or  services,  except  those  expressly  designated  by  IBM,  are  the  user's  responsibility. 

IBM  may  have  patents  or  pending  patent  applications  covering  subject  matter  in  this  document.  The 
furnishing  of  this  document  does  not  give  you  any  license  to  these  patents.  You  can  send  license 
inquiries,  in  writing,  to  the  IBM  Director  of  Commercial  Relations,  IBM  Corporation,  Purchase,  NY 
10577. 

The  following  terms,  denoted  by  an  asterisk^)  in  this  publication,  are  trademarks  of  the  IBM 
Corporation  in  the  United  States  and/or  other  countries: 

IBM 

Common  User  Access 
CUA 

Operating  System/2 
OS/2 

Presentation  Manager 
SAA 

System  Application  Architecture 

The  following  terms,  denoted  by  a double  asterisk  (**)  in  this  publication,  are  trademarks  of  other 


companies  as  follows: 
Adobe 

Adobe  Systems  Incorporated 

Helvetica 

Linotype  AG 

LaserJet 

Hewlett-Packard  Company 

Intel 

Intel  Corporation 

Microsoft 

Microsoft  Corporation 

PostScript 

Adobe  Systems  Incorporated 

Times  New  Roman 

Monotype  Corporation 

Windows 

Microsoft  Corporation 

Notices 
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WinShowWindow  — Show  Window  8-523 

WinShutdownSystem  - Shutdown  System  8-525 

WinStartApp  - Window  Start  Application  8-526 

WinStartTimer  - Start  Timer  8-529 

WinStopTimer  - Stop  Timer  8-531 

WinStoreWindowPos  - Store  Window  Position 8-533 

WinSubclassWindow  - Subclass  Window  8-534 

WinSubstituteStrings  - Substitute  Strings  8-536 

WinSubtractRect  - Subtract  Rectangle  8-538 

WinSwitchToProgram  - Switch  To  Program  8-540 

WinTerminate  - Terminate 8-542 

WinTerminateApp  - Terminate  Application 8-544 

WinTrackRect  - Draw  Tracking  Rectangle  8-546 

WinTranslateAccel  - Translate  Accelerator  8-550 

WinllnionRect  - Union  Rectangle 8-552 

WinUpdateWindow  - Update  Window  8-554 

WinUpper  - Uppercase  String  8-556 

WinUpperChar  - Uppercase  Character  8-558 

WinValidateRect  - Validate  Rectangle 8-560 

WinValidateRegion  - Validate  Region  8-562 

WinWaitEventSem  - Wait  Event  Semaphore  8-565 

WinWaitMsg  - Wait  Message  8-567 

WinWaitMuxWaitSem  - Wait  MuxWait  Semaphore  or  Message  8-569 

WinWindowFromDC  - Query  Window  Handle  From  Device  Context  8-572 

WinWindowFromID  - Query  Window  Handle  From  Identifier  8-574 

WinWindowFromPoint  - Window  From  Point  8-576 
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WPJob  9-21 

WPKeyboard  9-22 

WPMouse  9-23 

WPObject  9-24 

WPPalette  9-27 

WPPort  9-30 

WPPrinter  9-31 

WPPrinterDriver  9-33 

WPProgram 9-34 

WPProgramFile  9-37 

WPSchemePalette 9-40 

WPShadow  9-41 

WPShredder  9-43 

WPSound  9-44 

WPSpecialNeeds  9-45 
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WPStartup 9-47 

WPSystem  9-48 

WPTemplateFolder  9-49 
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WPQueueDriver  9-51 
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wpAddClockAlarmPage  - WPCIock  instance  method  9-53 

wpAddClockDateTimePage  - WPCIock  instance  method  9-54 

wpAddClockViewIPage  - WPCIock  instance  method  9-55 

wpAddClockView2Page  - WPCIock  instance  method  9-56 

wpAddCountryDatePage  - WPCountry  instance  method  9-57 

wpAddCountryNumbersPage  - WPCountry  instance  method  9-58 

wpAddCountryPage  - WPCountry  instance  method 9-59 

wpAddCountryTimePage  - WPCountry  instance  method  9-60 

wpAddDesktopLockupIPage  - WPDesktop  instance  method  9-61 

wpAddDesktopLockup2Page  - WPDesktop  instance  method  9-62 

wpAddDesktopLockup3Page  - WPDesktop  instance  method  9-63 

wpAddDiskDetailsPage  - WPDisk  instance  method  9-64 

wpAddFileMenuPage  - WPFileSystem  instance  method  9-65 

wpAddFileTypePage  - WPDataFile  instance  method  9-66 

wpAddFilelPage  — WPFileSystem  instance  method  9-67 

wpAddFile2Page  - WPFileSystem  instance  method  9-68 

wpAddFile3Page  - WPFileSystem  instance  method  9-69 

wpAddFolderBackgroundPage  - WPFolder  instance  method  9-70 

wpAddFolderlncludePage  - WPFolder  instance  method  9-71 

wpAddFolderSortPage  - WPFolder  instance  method  9-72 

wpAddFolderViewIPage  - WPFolder  instance  method  9-73 

wpAddFolderView2Page  - WPFolder  instance  method 9-74 

wpAddFolderView3Page  - WPFolder  instance  method  9-75 

wpAddKeyboardMappingsPage  - WPKeyboard  instance  method  9-76 

wpAddKeyboardSpecialNeedsPage  - WPKeyboard  instance  method  9-77 

wpAddKeyboardTimingPage  - WPKeyboard  instance  method  9-78 

wpAddMouseMappingsPage  - WPMouse  instance  method  9-79 

wpAddMouseTimingPage  - WPMouse  instance  method  9-80 

wpAddMouseTypePage  - WPMouse  instance  method  9-81 

wpAddObjectGeneralPage  - WPObject  instance  method  9-82 

wpAddProgramAssociationPage  - WPProgramFile  instance  method  9-83 

wpAddProgramAssociationPage  - WPProgram  instance  method  9-84 

wpAddProgramPage  - WPProgram  instance  method 9-85 

wpAddProgramPage  - WPProgramFile  instance  method  9-86 

wpAddProgramSessionPage  - WPProgram  instance  method 9-87 

wpAddProgramSessionPage  - WPProgramFile  instance  method  9-88 

wpAddSettingsPages  - WPObject  instance  method  9-89 

wpAddSoundWarningBeepPage  - WPSound  instance  method  9-90 

wpAddSystemConfirmationPage  - WPSystem  instance  method  9-91 

wpAddSystemLogoPage  - WPSystem  instance  method  9-92 

wpAddSystemPrintScreenPage  - WPSystem  instance  method  9-93 
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wpAddSystemWindowPage  — WPSystem  instance  method  9-94 

wpAddToObjUseList  - WPObject  instance  method  9-95 

wpAllocMem  - WPObject  instance  method  9-97 

wpCIose  - WPObject  instance  method 9-98 

wpCnrlnsertObject  - WPObject  instance  method  9-99 

wpCnrRemoveObject  - WPObject  instance  method 9-101 

wpCnrSetEmphasis  - WPObject  instance  method  9-102 

wpConfirmDelete  - WPObject  instance  method  9-103 

wpCopiedFromTemplate  - WPObject  instance  method  9-104 

wpCopyObject  - WPObject  instance  method  9-105 

wpCreateFromTemplate  - WPObject  instance  method  9-106 

wpCreateShadowObject  - WPObject  instance  method  9-107 

wpDelete  - WPObject  instance  method  9-108 

wpDeleteAllJobs  - WPPrinter  instance  method  9-109 

wpDeleteContents  - WPFolder  instance  method  9-110 

wpDeleteFromObjUseList  - WPObject  instance  method  9-111 

wpDeleteJob  - WPJob  instance  method 9-112 

wpDisplayHelp  - WPObject  instance  method 9-113 

wpDoesObjectMatch  - WPObject  instance  method  9-114 

wpDragCell  - WPPalette  instance  method  9-115 

wpDraggedOverObject  - WPObject  instance  method 9-116 

wpDragOver  - WPObject  instance  method  9-118 

wpDrop  - WPObject  instance  method  9-119 

wpDroppedOnObject  - WPObject  instance  method  9-120 

wpEditCell  - WPPalette  instance  method  9-121 

wpEndConversation  - WPObject  instance  method  9-122 

wpFilterPopupMenu  - WPObject  instance  method  9-123 

wpFindUseltem  - WPObject  instance  method  9-125 

wpFormatDragltem  - WPObject  instance  method  9-126 

wpFree  - WPObject  instance  method  9-127 

wpFreeMem  - WPObject  instance  method  9-128 

wpHide  - WPObject  instance  method  9-129 

wpHideFIdrRunObjs  - WPFolder  instance  method  9-130 

wpHoidJob  - WPJob  instance  method  9-131 

wpHoldPrinter  - WPPrinter  instance  method  9-132 

wpinitData  - WPObject  instance  method  9-133 

wpinsertPopupMenultems  - WPObject  instance  method 9-134 

wpinsertSettingsPage  - WPObject  instance  method  9-136 

wpisCurrentDesktop  - WPDesktop  instance  method  9-137 

wpMenultemHelpSelected  - WPObject  instance  method  9-138 

wpMenultemSelected  - WPObject  instance  method  9-139 

wpModifyPopupMenu  - WPObject  instance  method  9-140 

wpMoveObject  - WPObject  instance  method 9-141 

wpOpen  - WPObject  instance  method  9-142 

wpPaintCell  - WPPalette  instance  method  9-143 

wpPopulate  - WPFolder  instance  method  9-144 

wpPrintJobNext  - WPJob  instance  method  9-145 

wpPrintMetaFile  - WPDataFile  instance  method  9-146 

wpPrintObject  - WPObject  instance  method  9-147 

wpPrintPifFile  - WPDataFile  instance  method  9-148 

wpPrintPlainTextFile  - WPFileSystem  instance  method  9-149 

wpPrintPrinterSpecificFile  - WPDataFile  instance  method  9-150 

wpPrintUnknownFile  - WPDataFile  instance  method  9-151 

wpQueryAssociationFilter  - WPProgram  instance  method  9-152 

wpQueryAssociationFilter  - WPProgramFile  instance  method  9-153 

wpQueryAssociationType  - WPProgram  instance  method  9-154 

wpQueryAssociationType  - WPProgramFile  instance  method  9-155 

wpQueryComputerName  - WPPrinter  instance  method  9-156 

wpQueryConfirmations  - WPObject  instance  method  9-157 

wpQueryContent  - WPFolder  instance  method  9-158 

wpQueryDefaultHelp  - WPObject  instance  method  9-159 

wpQueryDefauitView  - WPObject  instance  method  9-160 

wpQueryDetailsData  - WPObject  instance  method  9-161 
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wpQueryError  - WPObject  instance  method  

wpQueryFIdrAttr  - WPFolder  instance  method  

wpQueryFIdrDetailsClass  - WPFolder  instance  method 

wpQueryFIdrFlags  - WPFolder  instance  method  

wpQueryFIdrFont  - WPFolder  instance  method  

wpQueryHandle  - WPObject  instance  method  

wpQuerylcon  - WPObject  instance  method  

wpQuerylconData  - WPObject  instance  method  

wpQueryLogicalDrive  - WPDisk  instance  method  

wpQueryNextlconPos  - WPFolder  instance  method  . . . 
wpQueryPaletteHelp  - WPPalette  instance  method  .... 
wpQueryPalettelnfo  - WPPalette  instance  method  .... 
wpQueryPrinterName  - WPPrinter  instance  method  . . . 
wpQueryProgDetails  - WPProgram  instance  method  . . . 
wpQueryProgDetails  - WPProgramFile  instance  method 
wpQueryRealName  - WPFileSystem  instance  method  . . 

wpQueryRootFolder  - WPDisk  instance  method  

wpQueryShadowedObject  - WPShadow  instance  method 

wpQueryStyle  - WPObject  instance  method  

wpQueryTitle  - WPObject  instance  method 

wpQueryType  - WPFileSystem  instance  method  

wpRedrawCell  - WPPalette  instance  method  

wpRefresh  - WPFileSystem  instance  method  

wpRegisterView  - WPObject  instance  method  

wpReleaseJob  - WPJob  instance  method 

wpReleasePrinter  - WPPrinter  instance  method  

wpRender  - WPObject  instance  method 

wpRenderComplete  - WPObject  instance  method  .... 
wpRestore  - WPObject  instance  method 

wpRestoreData  - WPObject  instance  method  

wpRestoreLong  - WPObject  instance  method  

wpRestoreState  - WPObject  instance  method 

wpRestoreString  - WPObject  instance  method  

wpSaveData  - WPObject  instance  method  

wpSaveDeferred  - WPObject  instance  method  

wpSavelmmediate  - WPObject  instance  method  

wpSaveLong  - WPObject  instance  method  

wpSaveState  - WPObject  instance  method  

wpSaveString  - WPObject  instance  method  

wpScanSetupString  - WPObject  instance  method  

wpSetAssociationFilter  - WPProgram  instance  method 
wpSetAssociationFilter  - WPProgramFile  instance  method 
wpSetAssociationType  - WPProgram  instance  method 
wpSetAssociationType  - WPProgramFile  instance  method 
wpSetComputerName  - WPPrinter  instance  method  . . . 

wpSetDefaultHelp  - WPObject  instance  method  

wpSetDefaultPrinter  - WPPrinter  instance  method  .... 

wpSetDefauitView  - WPObject  instance  method 

wpSetError  - WPObject  instance  method  

wpSetFIdrAttr  - WPFolder  instance  method  

wpSetFIdrDetailsClass  - WPFolder  instance  method  . . . 

wpSetFIdrFlags  - WPFolder  instance  method  

wpSetFIdrFont  - WPFolder  instance  method  

wpSetlcon  - WPObject  instance  method  

wpSetlconData  - WPObject  instance  method 

wpSetNextlconPos  - WPFolder  instance  method  

wpSetPalettelnfo  - WPPalette  instance  method  

wpSetPrinterName  - WPPrinter  instance  method  

wpSetProgDetails  - WPProgram  instance  method  .... 
wpSetProgDetails  - WPProgramFile  instance  method  . . 
wpSetRealName  - WPFileSystem  instance  method  .... 
wpSetShadowTitle  - WPShadow  instance  method  .... 
wpSetStyle  - WPObject  instance  method  
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wpSetTitle  - WPObject  instance  method  9-227 

wpSetType  - WPFileSystem  instance  method  9-228 

wpSetup  - WPObject  instance  method 9-229 

wpSetupCell  - WPPalette  instance  method  9-233 

wpShowPalettePointer  - WPPalette  instance  method  9-234 

wpStartJobAgain  - WPJob  instance  method  9-235 

wpSwitchTo  - WPObject  instance  method  9-236 

wpUnlockObject  - WPObject  instance  method  9-237 

wpUnlnitData  - WPObject  instance  method 9-238 
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wpcisCreateDefauItTemplates  - WPObject  class  method  9-240 

wpcisFindObjectEnd  - WPObject  class  method  9-241 

wpcisFindObjectFirst  - WPObject  class  method  9-242 

wpcisFindObjectNext  - WPObject  class  method  9-244 

wpcisinitData  - WPObject  class  method  9-246 

wpcisMakeAwake  - WPObject  class  method  9-247 

wpcisNew  - WPObject  class  method  9-249 

wpcIsQueryDefaultHelp  - WPObject  class  method  9-251 

wpcIsQueryDefauItView  - WPObject  class  method  9-252 

wpcIsQueryDetails  - WPObject  class  method  9-253 

wpcIsQueryDetailsInfo  - WPObject  class  method  9-254 

wpcIsQueryEditString  - WPPalette  class  method  9-257 

wpcIsQueryError  - WPObject  class  method  9-258 

wpcIsQueryFolder  - WPObject  class  method  9-259 
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wpcIsQuerylnstanceType  - WPFileSystem  class  method  9-263 

wpcIsQueryObject  - WPObject  class  method  9-264 

wpcIsQueryOpenFolders  - WPFolder  class  method  9-265 

wpcIsQuerySettingsPageSize  - WPObject  class  method 9-266 

wpcIsQueryStyle  — WPObject  class  method  9-267 
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wpcIsSetError  - WPObject  class  method  9-269 

wpcIsUnlnitData  - WPObject  class  method  9-270 
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Chapter  8.  Window  Functions 


Window  Functions  by  Functional  Area 

The  following  table  shows  how  all  of  the  Window  (WIN)  functions  are  related  within  functional  areas. 
The  functions  are  in  alphabetic  order  within  these  areas. 


C Name 

C Name 

Accelerators 

WinCopyAccelTable 

WinQueryAccelTable 

WinCreateAccelTable 

WinSetAccelTable 

WinDestroyAccelTable 

WinTranslateAccel 

WinLoadAccelTable 

Alarms 

WinAlarm  | WinMessageBox 

WinFlashWindow 

Atom  Manager 

WinAddAtom  WinQueryAtomLength 

WinCreateAtomTable  WinQueryAtomName 

WinDeleteAtom  WinQueryAtomUsage 

WinDestroyAtomTable  WinQuerySystemAtomTable 

WinFindAtom 


Button 

WinCheckButton 

WinQueryButtonCheckstate 

Clipboard 

WinCloseClipbrd 

WinQueryClipbrdOwner 

WinEmptyClipbrd 

WinQueryClipbrdViewer 

WinEnumClipbrdFmts 

WinSetClipbrdData 

WinOpenClipbrd 

WinSetClipbrdOwner 

WinQueryClipbrdOata 

WinSetClipbrdViewer 

WinQueryClipbrdFmtlnfo 

Coordinate  Mapping 


WinMakePoints  WinMapWindowPoints 

WinMapDIgPoints 


Cursor 

WinCreateCursor 

WinQueryCursorlnfo 

WinDestroyCursor 

WinShowCursor 

Dialog  Boxes 

WinCreateDIg 

WinFileDIg 

WinDefDIgProc 

WinFontDIg 

WinDefFileDIgProc 

WinFreeFileDIgList 
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C Name 

C Name 

WinDefFontDIgProc 

WinGetDIgMsg 

WinDismissDIg 

WinLoadDIg 

WinDIgBox 

WinProcessDIg 

WinEnableControl 

Drawing  Management 

Drawing 

WinBeginPaint 

WinLockVisRegions 

WinEnableWindowllpdate 

WinOpenWindowDC 

WinEndPaint 

WinQueryllpdateRect 

WinExciudellpdateRegion 

WinQueryllpdateRegion 

WinGetClipPS 

WinRealizePalette 

WinGetPS 

WinReleasePS 

WinGetScreenPS 

WinShowWindow 

WinlnvalidateRect 

WinllpdateWindow 

WinlnvalidateRegion 

WinValidateRect 

WinlsWindowShowing 

WinValidateRegion 

WinlsWindowVisible 

Drawing  Helpers 

WinDrawBitmap  WinlnvertRect 

WinDrawBorder  WinQueryPresParam 

WinDrawPointer  WinRemovePresParam 

WinDrawText  WinScrollWindow 

WinFillRect  WinSetPresParam 

WinGetSysBitmap 

Dynamic  Data  Exchange  (DDE)  Support 

WinDdelnitiate  WinDdeRespond 

WinDdePostMsg 

Error  Processing 

WinFreeErrorlnfo  WinGetLastError 

WinGetErrorlnfo 


Help  Manager 


WinAssociateHelpinstance 

WinDestroyHelpinstance 

WinCreateHelpinstance 

WinLoadHelpTable 

WinCreateHelpTable 

WinQueryHelpinstance 

Initialization  and  Termination 

WinCancelShutdown 

WinQueryAnchorBlock 

Winlnitialize 

WinQueryVersion 

WinTerminate 

Keyboard 

— 

WinEnablePhysinput 

WinlsPhysinputEnabled 
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C Name 

C Name 

WinFocusChange 

WinQueryFocus 

WinGetKeyState 

WinSetFocus 

W i nGetPhys  KeyState 

W i nSetKeyboardStateT  able 

Library  Support 

WinDeleteLibrary 

WinLoadLibrary 

WinDeleteProcedure 

WinLoadProcedure 

List  Box 

WinDeleteLboxitem 

WinQueryLboxitemTextLength 

WinlnsertLboxitem 

WinSetLboxitemText 

WinQueryLboxCount 

WinQueryLboxSelectedltem 

WinQueryLboxItemText 

Menus 

WinCheckMenultem  WinlsMenultemValid 

WinCreateMenu  WinLoadMenu 

WinEnableMenultem  WinPopupMenu 

WinlsMenultemChecked  WinSetMenultemText 

WinlsMenultemEnabled 


Message  Management 

WinBroadcastMsg 

WinQueryQueuelnfo 

WinCreateMsgQueue 

WinQueryQueueStatus 

WinDestroyMsgQueue 

WinRegisterllserDatatype 

WinDispatchMsg 

WinRegisterllserMsg 

WinGetMsg 

WinSendDIgltemMsg 

WinlnSendMsg 

WinSendMsg 

WinLoadMessage 

WinSetClassMsglnterest 

WinPeekMsg 

WinSetMsglnterest 

WinPostMsg 

WinSetMsgMode 

WinPostQueueMsg 

WinSetSynchroMode 

WinQueryMsgPos 

WinWaitMsg 

WinQueryMsgTime 

WinRequestMutexSem 

WinWaitEventSem 

WinWaitMuxWaitSem 

Mouse  Capture 

WinQueryCapture 

WinSetCapture 

Mouse  Tracking 

WinShowTrackRect 

WinTrackRect 

Pointer 

WinCreatePointer 

WinQueryPointerPos 

WinCreatePointerlndirect 

WinQuerySysPointer 

WinDestroyPointer 

WinSetPointer 

WinLoadPointer 

WinSetPointerPos 
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C Name 

C Name 

WinQueryPointer 

WinShowPointer 

WinQueryPointerlnfo 

Rectangles 

WinCopyRect 

WinOffsetRect 

WinEqualRect 

WinPtlnRect 

WinlnflateRect 

WinSetRect 

WinlntersectRect 

WinSetRectEmpty 

WinlsRectEmpty 

WinSubtractRect 

WinMakeRect 

WinUnionRect 

Standard  Window 

WinCalcFrameRect 

WinCreateStdWindow 

WinCreateFrameControls 

String/Character  and  Code  Pages 

WinCompareStrings 

WinQueryCp 

WinCpTranslateChar 

WinQueryCpList 

WinCpTranslateString 

WinSetCp 

WinLoadString 

WinSubstituteStrings 

WinNextChar 

WinUpper 

WinPrevChar 

WinllpperChar 

Task  List 

WinAddSwitchEntry 

WinQueryTaskSizePos 

WinChangeSwitchEntry 

WinQueryTaskTitle 

WinCreateSwitchEntry 

WinRemoveSwitchEntry 

WinQuerySessionTitle 

WinStartApp 

WinQuerySwitchEntry 

WinSwitchToProgram 

WinQuerySwitchHandle 

WinTerminateApp 

WinQuerySwitchList 


System  and  Queue  Hooks 


WinCallMsgFilter 


WinSetHook 


WinReleaseHook 


System  Colors 


WinQuerySysColor 


WinSetSysColors 


System  Modal  Management 


WinQuerySysModalWindow 


WinSetSysModalWindow 


System  Values 


Wi  nQuerySysVal  ue 


WinSetSysValue 


Timers 


WinGetCurrentTime 


WinStopTimer 


WinStartTimer 
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C Name 

C Name 

Window  Management 

Activation,  Size  and  Position 

WinGetMaxPosition 

W i nSaveWi  ndo  wPos 

WinGetMinPosition 

WinSetActiveWindow 

WinQueryActiveWindow 

WinSetMultWindowPos 

WinQueryWindowPos 

WinSetWindowPos 

Creation  and  Class  Information 

WinCreateWindow 

WinQueryClassName 

WinDefWindowProc 

WinRegisterClass 

WinDestroyWindow 

WinSubclassWindow 

WinQueryClassInfo 


General  Window  Information 

WinEnableWindow 

WinQueryWindowDC 

WinlsThreadActive 

WinQueryWindowProcess 

WinlsWindow 

WinQueryWindowRect 

WinlsWindowEnabled 

WinSetDesktopBkgnd 

WinQueryDesktopBkgnd 

WinWindowFromDC 

WinQueryDesktopWindow 

WinWindowFromID 

WinQueryObjectWindow 

WinWindowFromPoint 

Locking 

WinLockWindowllpdate 

Window  Hierarchies 

WinBeginEnumWindows 

WinMultWindowFromIDs 

WinEndEnumWindows 

WinQueryWindow 

WinEnumDIgltem 

WinSetOwner 

WinGetNextWindow 

WinSetParent 

WinlsChild 

Mixed  Memory  Model  Support 


WinQueryClassThunkProc  WinSetClassThunkProc 

WinQueryWindowModel  WinSetWindowThunkProc 

WinQueryWindowThunkProc 


Window  Text 

WinQueryDIgltemShort 

WinQueryWindowTextLength 

WinQueryDIgltemText 

WinSetDIgltemShort 

WinQueryDIgltemTextLength 

WinSetDIgltemText 

WinQueryWindowText 

WinSetWindowText 

Window  Words 

WinQueryWindowPtr 

WinSetWindowPtr 

WinQueryWindowULong 

WinSetWindowULong 

WinQueryWindowUShort 

WinSetWindowUShort 
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WinSetWindowBits 
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WinAddAtom  - 
Add  Atom 


#define  INCL_WINATOM  /*  Or  use  INCL_WIN  or  INCL_PM  7 


ATOM  WinAddAtom  (HATOMTBL  hatomtbiAtomTbl,  PSZ  pszAtomName) 


This  function  adds  an  atom  to  an  atom  table. 

Parameters 

hatomtbiAtomTbl  (HATOMTBL)  - input 
Atom-table  handle. 

This  is  the  handle  returned  by  a previous  call  to  WinCreateAtomTable  or 
WinQuerySystemAtomTable. 

pszAtomName  (PSZ)  - input 
Atom  name. 

This  is  a character  string  to  be  added  to  the  table. 

If  the  string  begins  with  an  character,  the  five  ASCII  digits  that  follow  are  converted  into  an 
integer  atom.  If  this  integer  is  a valid  integer  atom,  this  function  returns  that  atom,  without 
modifying  the  atom  table. 

If  the  string  begins  with  an  “!”  character,  the  next  two  bytes  are  interpreted  as  an  atom.  If  it  is 
an  integer  atom,  that  atom  is  returned.  If  it  is  not  an  integer  atom  and  it  is  a valid  atom  for  the 
given  atom  table  (that  is,  it  has  an  atom  name  and  use  count  associated  with  it)  the  use  count  of 
that  atom  is  incremented  by  one  and  the  atom  is  returned.  Otherwise  0 is  returned. 

If  the  high  order  word  of  the  string  is  minus  one,  the  low  order  word  is  an  atom.  If  it  is  an  integer 
atom,  that  atom  is  returned.  If  it  is  not  an  integer  atom  and  it  is  a valid  atom  for  the  given  atom 
table  (that  is,  it  has  an  atom  name  and  use  count  associated  with  it)  the  use  count  of  that  atom  is 
incremented  by  one  and  the  atom  is  returned.  Otherwise  0 is  returned. 


Returns 

Atom  value: 

Atom  The  atom  associated  with  the  passed  string 
0 Invalid  atom-table  handle  or  invalid  atom  name  specified. 

Possible  returns  from  WinGetLastError 

PMERRINVALIDHATOMTBL 
PMERRINVALIDINTEGERATOM 
PMERRINVALIDATOMNAME 
PMERRATOMNAMENOTFOUND 

Remarks 

If  the  atom  name  represents  an  integer  atom,  this  function  returns  the  atom  represented  by  the 
passed  atom  name. 

If  the  atom  name  does  not  represent  an  integer  atom  and  if  the  atom  name  already  exists  in  the  atom 
table,  this  function  increments  the  use  count  of  that  atom  by  one.  Otherwise,  the  atom  is  added  to  the 
table  and  its  use  count  is  set  to  one.  In  either  case  this  function  returns  the  atom  represented  by  the 
passed  atom  name. 


An  invalid  atom-table  handle  was  specified. 

The  specified  atom  is  not  a valid  integer  atom. 

An  invalid  atom  name  string  was  passed. 

The  specified  atom  name  is  not  in  the  atom  table. 
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Win  Add  Atom  - 
Add  Atom 


Related  Functions 

• WinCreateAtomTable 

• WinDeleteAtom 

• WinDestroyAtomTable 

• WinFindAtom 

• WinQueryAtomLength 

• WinQueryAtomName 

• WinQueryAtom  Usage 

• WinQuerySystemAtomTable 

Example  Code 

This  example  creates  an  Atom  Table  and  then  adds  the  atom  'newatom'  to  the  new  table;  it  then 
checks  the  count  for  this  new  atom  to  verify  that  it  is  1 . 


Idefine  INCL_WINATOM  /*  Window  Atom  Functions  */ 
linclude  <os2.h> 

ATOM  atom;  /*  new  atom  value  */ 
HATOMTBL  hatomtbl AtomTbl ; /*  atom-table  handle  */ 
char  pszAtomName[10] ; /*  atom  name  */ 
ULONG  ul Initial  = 0;  /*  initial  atom  table  size  (use  default)*/ 
ULONG  ulBuckets  = 0;  /*  size  of  hash  table  (use  default)  */ 
ULONG  ul Count;  /*  atom  usage  count  */ 
BOOL  atomCountl  = FALSE;/*  indicates  atom  count  ==  1 */ 


/*  create  atom  table  of  default  size  */ 

hatomtbl AtomTbl  = WinCreateAtomTable(ul Initial , ulBuckets); 

/*  define  name  for  new  atom  and  add  to  table  */ 

strcpy(pszAtomName, "newatom") ; 

atom  = WinAddAtom(hatomtbl AtomTbl , pszAtomName) ; 

ulCount  = WindQueryAtomUsage(hatomtblAtomTbl , atom); 

/*  verify  that  usage  count  is  1 */ 
if  (ulCount  ==  1) 
atomCountl  = TRUE; 
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WinAddSwitchEntry  - 
Add  Switch  Entry 


#define  INCL_WINSWITCHLIST  /*  Or  use  INCL_WIN  or  INCL_PM.  Also  in  COMMON  section  */ 


HSWITCH  WinAddSwitchEntry  (PSWCNTRL  pswctiSwitchData) 


This  function  adds  an  entry  to  the  Window  List.  This  is  a list  of  running  programs  that  is  displayed  to 
the  user  by  the  operating  system. 


Parameters 

pswctiSwitchData  (PSWCNTRL)  - input 
Switch  data. 

Contains  information  about  the  newly  created  Window  List  entry. 

If  the  szSwtitle[MAXNAMEL  + 7]  field  of  the  SWCNTRL  structure  is  0,  the  system  uses  the  name 
under  which  the  application  is  started.  This  only  applies  for  programs  written  for  OS/2  Versions 
1.1  and  later,  and  only  for  the  first  call  to  this  function  since  the  program  started.  Otherwise,  a 
NULL  entry  name  is  invalid. 

The  title  is  truncated,  if  necessary,  to  60  characters. 

If  the  hprog  field  of  the  SWCNTRL  structure  is  NULLHANDLE,  the  value  used  by  the  system  when 
the  program  was  loaded  (if  it  has  been  loaded)  is  substituted. 

If  the  idProcess  field  of  the  SWCNTRL  structure  is  0,  the  current  process  ID  is  used. 

If  the  idSession  field  of  the  SWCNTRL  structure  is  0,  the  current  session  ID  is  used. 

If  the  hwndlcon  field  of  the  SWCNTRL  structure  is  NULLHANDLE,  the  system  supplies  a default 
icon. 


Returns 

Handle  to  the  newly  created  Window  List  entry. 

There  is  a system  limit  to  the  number  of  Window  List  entries.  However,  this  is  a large  number 
(several  hundred)  and  is  unlikely  to  be  reached  in  practice  because  other  system  limits,  such  as 
memory  size,  restrict  the  number  before  this  limit  is  reached. 

NULLHANDLE  Error  occurred 

Other  Handle  to  the  newly  created  Window  List  entry. 

Possible  returns  from  WinGetLastError 

PMERR  NO  SPACE  The  limit  on  the  number  of  Window  List  entries  has  been 

reached  with  WinAddSwitchEntry. 

PMERRJNVALID_WINDOW  The  window  specified  with  a Window  List  function  is  not  a 

valid  frame  window. 

PMERR_INVALID_SESSION_ID  The  specified  session  identifier  is  invalid.  Either  zero  (for 

the  application’s  own  session)  or  a valid  identifier  must 
be  specified. 


Remarks 

Neither  this  function  nor  the  WinRemoveSwitchEntry  function  are  required  if  the  main  window  is 
created  with  the  frame  creation  flags  FCF_TASKLIST  or  FCF_STANDARD,  because  these  flags 
automatically  update  the  Window  List  when  the  main  window  is  created  or  destroyed. 


Chapter  8.  Window  Functions  8-9 


WinAddSwitchEntry 
Add  Switch  Entry 


Related  Functions 

• WinChangeSwitchEntry 

• WinCreateSwitchEntry 

• WinQuerySessionTitle 

• WinQuerySwitchEntry 

• WinQuerySwitchHandle 

• WinQuerySwitchList 

• WinQueryTaskSizePos 

• WinQueryTaskTitle 

• WinRemoveSwitchEntry 

• WinSwitchToProgram 


Example  Code 

This  example  calls  WinQueryWindowProcess  to  get  the  current  process  identifier  (needed  for  the 
SWCNTRL  structure).  It  then  sets  up  the  swctl  structure  and  calls  WinAddSwitchEntry  to  add  the 
name  of  the  program  to  the  task  list.  The  returned  handle  can  be  used  in  subsequent  calls  to 
WinChangeSwitchEntry  if  the  title  needs  to  be  changed.  The  variables  swctl,  hswitch,  and  pid  should 
be  global  if  the  application  will  be  calling  the  WinChangeSwitchEntry  function  to  avoid  having  to  set 
up  the  structure  again. 


fdefine  INCL_WINSWITCHLIST  /*  Window  Task  Switch  Functions  */ 
linclude  <os2.h> 


SWCNTRL  swctl;  /*  switch  control  data  */ 
HSWITCH  hswitch;  /*  switch  handle  */ 
PID  pid;  /*  process  id  */ 
HWND  hwndFrame;  /*  frame  handle  */ 


WinQueryWindowProcess(hwndFrame,  &pid,  NULL); 


swctl. hwnd  = hwndFrame; 

swctl. hwndlcon  = NULLHANDLE; 

swctl. hprog  = NULLHANDLE; 

swctl .idProcess  = pid; 

swctl .idSession  = 0; 

swctl .uchVi Sibil ity  = SWL_VISIBLE; 

swctl. fbJump  = SWL_JUMPABLE; 

swctl .szSwti tie [0]  = 0; 


/*  window  handle  */ 
/*  icon  handle  */ 
/*  program  handle  */ 
/*  process  identifier  */ 
/*  session  identifier  */ 
/*  visibility  */ 
/*  jump  indicator  */ 
/*  program  name  */ 


hswitch  = WinAddSwitchEntry(&swctl) ; 
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WinAlarm  - 
Sound  Alarm 


#define  INCL_WINDIALOGS  /*  Or  use  INCL_WIN  or  INCL_PM.  Also  in  COMMON  section  7 


BOOL  WinAlarm  (HWND  hwndDeskTop,  ULONG  fIStyle) 


This  function  generates  an  audible  alarm. 


Parameters 

hwndDeskTop  (HWND)  - input 
Desktop-window  handle: 

HWND_DESKTOP  The  desktop  window 

Other  Specified  desktop  window. 

(IStyle  (ULONG)  - input 
Alarm  style. 

Used  to  signify  different  situations  to  the  operator. 

The  duration  and  frequency  of  the  alarms  can  be  changed  by  the  WinSetSysValue  function.  The 
alarm  frequency  is  defined  to  be  in  the  range  X 1 0025 1 through  X 1 7FFF 1 . The  alarm  is  not 
generated  if  system  value  SV_ALARM  is  set  to  FALSE.  The  alarms  are  dependent  on  the  device 
capability. 

Different  alarms  are  selected  by  use  of  these  values: 

WA_WARNING 

WA_NOTE 

WAERROR 

Returns 

Alarm-generated  indicator: 

TRUE  Alarm  generated 
FALSE  Alarm  not  generated. 

Possible  returns  from  WinGetLastError 

PMERR  INVALID  HWND  An  invalid  window  handle  was  specified. 

PMERR_INVALID_FLAG  An  invalid  bit  was  set  for  a parameter.  Use  constants 

defined  by  PM  for  options,  and  do  not  set  any  reserved 
bits. 


Remarks 

Although  this  function  is  in  the  INCL_WINDIALOGS  section,  it  is  part  of  the  common  subset  and  is 
also  included  if  INCL_COMMON  is  defined. 

Related  Functions 

• WinFlashWindow 

• WinMessageBox 
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WinAlarm  - 
Sound  Alarm 


Example  Code 

This  example  calls  an  application-defined  initialization  function,  and  calls  WinAlarm  to  generate 
audible  alarm  to  notify  the  user  if  the  function  fails. 

fdefine  INCL_WINDIALOGS  /*  Window  Dialog  Mgr  Functions  */ 

linclude  <os2.h> 

if  (IGenericInitO)  /*  general  initialization  */ 

Wi  nAl  a rm( HWND_DESKTOP , WA_ERR0R) ; 
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WinAssociateHelpInstance  - 
Associate  Help  Instance 


#define  INCL_WINHELP  /*  Or  use  INCL_WIN  or  INCL_PM  7 


BOOL  WinAssociateHelpInstance  (HWND  hwndHelpInstance,  HWND  hwndApp) 


This  function  associates  the  specified  instance  of  the  help  manager  with  the  window  chain  of  the 
specified  application  window. 


Parameters 

hwndHelpInstance  (HWND)  - input 

Handle  of  an  instance  of  the  help  manager. 

This  is  the  handle  returned  by  the  WinCreateHelpInstance  call. 

NULLHANDLE  Dissociates  an  instance  of  the  help  manager  from  a window  chain  when  the 
instance  has  been  destroyed. 

Other  The  handle  of  an  instance  of  the  help  manager  to  be  associated  with  the 

application  window  chain. 

hwndApp  (HWND)  - input 

Handle  of  an  application  window. 

The  handle  of  the  application  window  with  which  the  instance  of  the  help  manager  will  be 
associated.  The  instance  of  the  help  manager  is  associated  with  the  application  window  and  any 
of  its  children  or  owned  windows. 

Returns 

Success  indicator: 

TRUE  Successful  completion 
FALSE  Error  occurred. 

Remarks 

In  order  to  provide  help,  the  application  must  associate  an  instance  of  the  help  manager  with  a chain 
of  application  windows.  This  association  lets  the  help  manager  know  which  instance  should  provide 
the  help  function. 

The  help  manager  traces  the  window  chain,  starting  from  the  window  where  help  is  requested.  The 
application  window  in  the  chain  with  the  associated  help  instance  will  be  the  one  with  which  the  help 
manager  communicates  and  next  to  which  the  help  window  is  positioned,  unless  a 
HM_SET_ACTIVE_WINDOW  message  is  sent  to  the  help  manager.  If  the  HM_SET_ACTIVE_WINDOW 
message  is  sent  to  the  help  manager,  the  active  window  parameter  is  the  window  with  which  the 
help  manager  communicates.  The  help  manager  positions  the  help  window  next  to  the  window 
specified  as  the  relative  window. 


Related  Functions 

• WinCreateHelpInstance 

• WinCreateHelpTable 

• WinDestroyHelpInstance 

• WinLoadHelpTable 

• WinQueryHelpInstance 
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WinAssociateHelpInstance 
Associate  Help  Instance 


Related  Messages 

• HM_SET_ACTIVE_WINDOW 


Example  Code 

This  example  shows  a typical  main  function  for  an  application  which  uses  help.  Following  creation  of 
the  main  application  window  the  help  manager  is  initialized  and  associated  with  the  window.  The 
help  table  is  defined  in  the  application's  resources.  When  the  window  is  destroyed,  terminating  the 
application,  the  help  instance  is  also  destroyed. 


fdefine  INCL=_WIN 
finclude  <os2.h> 

fdefine  IDHT_APPLICATION  100  /*  id  of  HELP  TABLE  in  resource  file 

*/ 

main(  int  argc,  char  *argv[],  char  *envp[]  ) 

{ 

HAB  hab  = Winlnitial  ize(  0 ); 

HMQ  hmq  = WinCreateMsgQueue(  hab,  0 ); 

HWNO  hwnd; 

HWND  hwndClient; 

HWND  hwndHelp; 

QMSG  qmsg; 

ULONG  fl Style; 

HELPINIT  helpinit; 

/*  Setup  the  help  initialization  structure  */ 
helpinit. cb  = sizeof(  HELPINIT  ); 
helpinit.ulReturnCode  = 0L; 
helpinit. pszTutorialName  = (PSZ)NULL; 

/*  Help  table  in  application  resource  */ 

helpinit. phtHelpTable  = (PHELPTABLE)MAKEULONG(  IDHT_APPLICATION,  0xffff  ); 
helpinit.hmodHelpTableModule  = NULLHANDLE; 

/*  Default  action  bar  and  accelerators  */ 
helpinit.hmodAccelActionBarModule  = NULLHANDLE; 
helpinit. idAccelTable  = 0; 
helpinit.idActionBar  = 0; 
helpinit.pszHelpWindowTitle  = "APPNAME  HELP"; 
helpinit. fShowPanel Id  = CMIC_SHOW_PANEL_ID; 
helpinit. pszHelpLibraryName  = " APPNAME. HLP"; 

/*  Register  the  class  */ 
if(  WinRegisterClass(  ...  ) ) 

{ 

/*  create  the  main  window  */ 

fl Style  = FCF_STANDARD; 

hwnd  = WinCreateStdWindow(  ...  ); 

if(  hwnd  ) 

{ 

/*  Create  and  associate  the  help  instance  */ 
hwndHelp  = WinCreateHelpInstance(  hab,  &helpinit  ); 

if(  hwndHelp  &&  WinAssociateHelpInstance(  hwndHelp,  hwnd  ) ) 

{ 

/*  Process  messages  */ 

whi 1 e ( WinGetMsg(  hab,  &qmsg,  NULLHANDLE,  0,  0 ) ) 

{ 

WinDispatchMsg(  hab,  Sqmsg  ); 

} /*  endwhile  */ 

} 
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WlnAssoclateHelpInstance  - 
Associate  Help  Instance 


/*  Remove  help  instance  - note:  add  */ 

/*  WinAssociateHelpInstance(  NULLHANDLE,  hwnd  );  */ 

/*  to  WM_DESTROY  processing  to  remove  the  association.  */ 
WinDestroyHelpInstance(  hwndHelp  ); 

} 

} 

/*  finish  the  cleanup  and  exit  */ 

WinDestroyMsgQueue(  hmq  ); 

WinTerminate(  hab  ); 
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WinBeginEnumWindows  - 
Begin  Window  Enumeration 


#define  INCL_WINWINDOWMGR  /*  Or  use  INCL_WIN  or  INCL_PM  */ 


HENUM  WinBeginEnumWindows  (HWND  hwndParent) 


This  function  begins  the  enumeration  process  for  all  of  the  immediate  child  windows  of  a specified 
window. 

Parameters 

hwndParent  (HWND)  - input 

Handle  of  the  window  whose  child  windows  are  to  be  enumerated: 

HWND  DESKTOP  Enumerate  all  main  windows 
HWND  OBJECT  Enumerate  all  object  windows 

Other  Enumerate  all  immediate  children  of  the  specified  window. 

Returns 

Enumeration  handle. 

This  is  used  in  subsequent  calls  to  the  WinGetNextWindow  function  to  return  the  immediate 
child-window  handles  in  succession. 

When  the  application  has  finished  the  enumeration,  the  enumeration  handle  must  be  destroyed 
with  the  WinEndEnumWindows  call. 

Possible  returns  from  WinGetLastError 

PMERRINVALIDHWND  An  invalid  window  handle  was  specified. 

Remarks 

This  function  remembers  the  window  hierarchy  at  the  time  of  invocation  of  the  call.  Thereafter  the 
information  is  referenced  by  use  of  the  Henum  parameter  and  does  not  change  during  the 
enumeration  by  the  WinGetNextWindow  call.  The  windows  are  enumerated  in  the  z-order  at  the  time 
enumeration  is  begun,  with  the  topmost  child  window  enumerated  first. 

Only  the  immediate  children  of  the  specified  window  are  enumerated;  child  windows  of  the  child 
windows  are  excluded. 

The  enumerated  windows  are  not  locked  by  this  function  and  can  thus  be  destroyed  between  the  time 
that  it  is  called  and  the  time  that  the  WinGetNextWindow  function  is  used  to  obtain  the  handle  for  the 
window. 

Related  Functions 

• WinEndEnumWindows 

• WinEnumDIgltem 

• WinGetNextWindow 

• WinlsChild 

• WinMultWindowFromIDs 

• WinQueryWindow 

• WinSetOwner 

• WinSetParent 
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WinBeginEnumWindows  - 
Begin  Window  Enumeration 


Example  Code 

This  example  begins  window  enumeration  of  all  main  windows  (i.e.  all  immediate  children  of  the 
Desktop),  after  which  WinGetNextWindow  is  called  in  a loop  to  enumerate  all  the  children,  until  all 
children  are  found  and  the  enumeration  ends. 


Idefine  INCL_WINWINDOWMGR  /*  Window  Manager  Functions  */ 

linclude  <os2.h> 


HWND  hwndParent; 

HWND  hwndNext; 

HENUM  henum; 

BOOL  f Success; 

SHORT  sRetLen; 

SHORT  s Length  = 10; 
char  pchBuffer[10] ; 


/*  Handle  of  the  window  whose  child  windows 


are  to  be  enumerated  */ 
/*  current  enumeration  handle  */ 
/*  enumeration  handle  */ 
/*  success  indicator  */ 
/*  returned  string  length  */ 
/*  string  buffer  length  */ 
/*  string  buffer  */ 


hwndParent  = HWNDJESKTOP; 


henum  = WinBeginEnumWindows(hwndParent) ; 


while  ((hwndNext  = WinGetNextWindow(henum))  !=  NULLHANDLE)  { 


} ‘ 

f Success  = WinEndEnumWindows  (henum); 
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WinBeginPaint 
Begin  Paint 


#define  INCL_WINWINDOWMGR  /*  Or  use  INCL_WIN  or  INCL_PM.  Also  in  COMMON  section  */ 


HPS  WinBeginPaint  (HWND  hwnd,  HPS  bps,  PRECTL  prcIRect) 


This  function  obtains  a presentation  space  whose  associated  update  region  is  set  ready  for  drawing 
in  a specified  window. 

Parameters 

hwnd  (HWND)  - input 

Handle  of  window  where  drawing  is  going  to  occur: 

HWND_DESKTOP  The  desk  top  window. 

Other  Specified  window. 

hps  (HPS)  - input 

Presentation-space  handle: 

NULLHANDLE  Obtain  a cache  presentation  space. 

Other  Presentation-space  handle.  This  function  sets  its  clipping  region  to  the  update 

region  of  the  hwnd  parameter. 

prcIRect  (PRECTL)  - output 
Bounding  rectangle: 

Note:  The  value  of  each  field  in  this  structure  must  be  in  the  range -32  768  through  32  767.  The 
data  type  WRECT  can  also  be  used,  if  supported  by  the  language. 

NULL  No  bounding  rectangle;  that  is,  repainting  is  not  required. 

Other  Specifies  the  smallest  rectangle  bounding  the  update  region,  in  window  coordinates. 

Returns 

Presentation-space  handle: 

NULLHANDLE  Error  occurred 

Other  Presentation-space  handle. 

Possible  returns  from  WinGetLastError 

PMERRJNVALIDHWND 
PMERRJNVHPS 

Remarks 

This  function  is  generally  made  during  the  processing  of  a WM  PAINT  message  when  the  application 
needs  to  update  the  content  of  the  window. 

If  the  presentation  space  already  exists,  its  update  region  is  set  and  the  device  context  of  the  window 
is  associated  with  the  presentation  space.  Otherwise,  a cache  presentation  space  is  obtained 
specifically  for  the  window. 

The  update  region  associated  with  hwnd  is  reset  to  NULLHANDLE.  It  is  assumed  that  any  drawing 
following  this  function  restores  the  content  of  the  window  to  a fully  correct  state. 

This  function  hides  the  pointer  if  it  is  in  the  window  and  the  WinEndPaint  function  restores  it. 


An  invalid  window  handle  was  specified. 

An  invalid  presentation-space  handle  was  specified. 
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WinBeglnPaint  - 
Begin  Paint 


This  function  hides  the  tracking  rectangle  if  it  is  active  and  might  hide  part  of  the  painting  window; 
that  is,  if  hwnd  is  a child  of  the  window  specified  by  the  hwnd  parameter  in  the  WinTrackRect 
function.  The  WinEndPaint  function  shows  it  again. 

WinEndPaint  must  be  called  after  the  application  completes  drawing,  and  can  be  nested  for  the  same 
window. 

Related  Functions 

• WinEnableWindowllpdate 

• WinEndPaint 

• WinExcludellpdateRegion 

• WinGetClipPS 

• WinGetPS 

• WinGetScreenPS 

• WinlnvalidateRect 

• WinlnvalidateRegion 

• WinlsWindowShowing 

• WinlsWindowVisible 

• WinLockVisRegions 

• WinOpenWindowDC 

• WinQueryllpdateRect 

• WinQueryllpdateRegion 

• WinRealizePalette 

• WinReleasePS 

• WinShowWindow 

• WinUpdateWindow 

• WinValidateRect 

• WinValidateRegion 

Related  Messages 

• WM_PAINT 

Example  Code 

This  example  uses  WinBeginPaint  to  obtain  and  associate  a presentation  space  with  the  update 
region  of  a window  so  that  redrawing  can  take  place. 


fdefine  INCL_WINWINDOWMGR  /*  Window  Manager  Functions  */ 

linclude  <os2.h> 

HWND  hwnd;  /*  parent  window  */ 

RECTL  rcl ; /*  update  region  */ 

HPS  hps;  /*  presentation-space  handle  */ 

case  WM_PAINT: 

hps  = WinBeginPaint(hwnd,  /*  handle  of  the  window  */ 


NULLHANDLE,  /*  get  a cache  presentation  space  */ 

&rcl);  /*  receives  update  rectangle  */ 

Wi nFi 1 1 Rect (hps , &rcl , CLR_WHITE) ; 

WinEndPaint(hps) ; 
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WinBroadcastMsg  • 
Broadcast  Message 


#define  INCL_WINMESSAGEMGR  /*  Or  use  INCL_WIN  or  INCL_PM  */ 


BOOL  WinBroadcastMsg  (HWND  hwndParent,  ULONG  uiMsgld,  MPARAM  mpParaml, 
MPARAM  mpParam2,  ULONG  fICmd) 


This  function  broadcasts  a message  to  multiple  windows. 


Parameters 

hwndParent  (HWND)  - input 
Parent-window  handle. 

uiMsgld  (ULONG)  - input 
Message  identifier. 

mpParaml  (MPARAM)  - input 
Parameter  1 . 


mpParam2  (MPARAM)  - input 
Parameter  2. 


fICmd  (ULONG)  - input 

Broadcast  message  command: 

BMSG_POST  Post  the  message.  This  value  is  mutually  exclusive  with  BMSG_SEND 

and  BMSG_POSTQUEUE. 


BMSGSEND  Send  the  message.  This  value  is  mutually  exclusive  with  BMSG_POST 

and  BMSG_POSTQUEUE. 


BMSGPOSTQUEUE  Post  a message  to  all  threads  that  have  a message  queue.  This  value 
is  mutually  exclusive  with  BMSG_POST  and  BMSG_SEND.  The  hwnd 
parameter  of  the  QMSG  structure  is  set  to  NULL. 


BMSG_DESCENDANTS 

BMSGFRAMEONLY 


Broadcast  the  message  to  all  the  descendants  of  the  hwndParent 
parameter. 

Broadcast  the  message  only  to  windows  with  a style  of  CS_FRAME. 


Returns 

Success  indicator: 

TRUE  Message  was  sent  or  posted  successfully  to  all  applicable  windows 
FALSE  Error  occurred. 

Remarks 

This  function  sends  or  posts  a message  to  all  the  immediate  child  windows  of  hwndParent,  except  in 
the  case  when  fICmd  is  BMSG_DESCENDANTS. 

The  uiMsgld,  mpParaml,  and  mpParam2  parameters  make  up  the  message  sent  or  posted.  The 
window  handle  of  the  receiving  window  is  added  to  the  message. 
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WinBroadcastMsg  - 
Broadcast  Message 


Related  Functions 

• WinCreateMsgQueue 

• WinDestroyMsgQueue 

• WinDispatchMsg 

• WinGetDIgMsg 

• WinGetMsg 

• WinlnSendMsg 

• WinPeekMsg 

• WinPostMsg 

• WinPostQueueMsg 

• WinQueryMsgPos 

• WinQueryMsgTime 

• WinQueryQueuelnfo 

• WinQueryQueueStatus 

• WinRegisterllserDatatype 

• WinRegisterllserMsg 

• WinSendDIgltemMsg 

• WinSendMsg 

• WinSetClassMsglnterest 

• WinSetMsglnterest 

• WinSetMsgMode 

• WinSetSynchroMode 

• WinWaitMsg 

Example  Code 

This  example  broadcasts  a WM  CLOSE  message  to  all  descendants  of  the  specified  window. 


Idefine  INCL_WINMESSAGEMGR  /*  Window  Message  Functions  */ 
finclude  <os2.h> 

BOOL  f Success;  /*  Success  indicator  */ 
HWND  hwndParent;  /*  parent  window  handle  */ 
ULONG  ulMsgld;  /*  Message  identifier  */ 
MPARAM  mpParaml;  /*  Parameter  1 */ 
MPARAM  mpParam2;  /*  Parameter  2 */ 
ULONG  flCmd;  /*  message  command  */ 


/*  set  msg  to  close  window,  parameters  to  NULL  */ 
ulMsgld  = WM_CL0SE; 
mpParaml  = MPVOID; 
mpParam2  = MPVOID; 

/*  broadcast  to  all  descendants  */ 
flCmd  = BMSG_DESCENDANTS; 

fSuccess  = WinBroadcastMsg(hwndParent,  ulMsgld,  mpParaml, 

mpParam2,  flCmd); 
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WinCalcFrameRect  - 
Calculate  Frame  Rectangle 


#define  INCL_WINFRAMEMGR  /*  Or  use  INCL.WIN  or  INCL_PM  */ 


BOOL  WinCalcFrameRect  (HWND  hwnd,  PRECTL  prciRect,  BOOL  fFrame) 


This  function  calculates  a client  rectangle  from  a frame  rectangle,  or  a frame  rectangle  from  a client 
rectangle. 


Parameters 

hwnd  (HWND)  - input 
Frame-window  handle. 

prciRect  (PRECTL)  - input/output 
Window  rectangle. 

Note:  The  value  of  each  field  in  this  structure  must  be  in  the  range  -32  768  through  32  767.  The 
data  type  WRECT  can  also  be  used,  if  supported  by  the  language. 

fFrame  (BOOL)  - input 
Frame  indicator: 

TRUE  Frame  rectangle  provided 
FALSE  Client-area  rectangle  provided. 

Returns 

Rectangle-calculated  indicator: 

TRUE  Rectangle  successfully  calculated 

FALSE  Error  occurred,  or  the  calculated  rectangle  is  empty. 

Possible  returns  from  WinGetLastError 

PMERRJNVALID_HWND  An  invalid  window  handle  was  specified. 

Remarks 

This  function  provides  the  size  and  position  of  the  client  area  within  the  specified  frame  rectangle  for 
the  specified  frame  window,  or  conversely,  the  size  and  position  of  the  frame  window  that. would 
contain  a client  window  of  the  specified  size  and  position. 

This  function  sends  a WM  CALCFRAMERECT  message  to  the  frame  window.  This  enables  a 
subclassed  frame  control  to  implement  the  calculation  correctly. 

This  function  works  if  hwnd  is  hidden;  hwnd  should  be  hidden  if  it  is  required  that  the  window  shows 
a particular  client  rectangle  when  the  window  is  first  shown. 


Related  Functions 

• WinCreateFrameControls 

• WinCreateStdWindow 

• WinCreateWindow 

• WinDefWindowProc 

• WinDestroyWindow 

• WinQueryClassInfo 

• WinQueryClassName 

• WinRegisterClass 

• WinSubclassWindow 
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WinCalcFrameRect  - 
Calculate  Frame  Rectangle 


Related  Messages 

• WM_CALCFRAMERECT 

Example  Code 

This  example  converts  a client  window's  boundaries  into  screen  coordinates  and  calls 
WinCalcFrameRect  to  calculate  an  equivalent  frame  rectangle  size. 

Idefine  INCL_WINFRAMEMGR  /*  Window  Frame  Functions  */ 

Idefine  INCL_WINWINDOWMGR  /*  Window  Manager  Functions  */ 

linclude  <os2.h> 

BOOL  f Success;  /*  Success  indicator  */ 

HWND  hwndClient;  /*  client  window  */ 

HWND  hwndFrame;  /*  frame  window  */ 

RECTL  rcl Boundary;  /*  Boundary  rectangle  */ 

/*  convert  client  boundary  coordinates  to  screen  coordinates  */ 

Wi nMapWi ndowPoi nts ( hwndCl i ent , HWND_DESKTOP , ( PPOINTL) &rcl Boundary , 

2); 

/*  calculate  equivalent  frame  boundary  from  boundary  data  */ 
fSuccess  = WinCalcFrameRect (hwndFrame,  &rclBoundary,  FALSE); 
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WinCallMsgFilter  - 
Call  Message  Filter 


#define  INCL_WINHOOKS  /*  Or  use  INCL_WIN  or  INCL_PM  */ 


BOOL  WinCallMsgFilter  (HAB  hab,  PQMSG  pqmsgpqmsg,  ULONG  uiFllter) 


This  function  calls  a message-filter  hook. 


Parameters 

hab  (HAB)  - input 

Anchor-block  handle. 

pqmsgpqmsg  (PQMSG)  - input 

Message  to  be  passed  to  the  message-filter  hook. 

uiFllter  (ULONG)  - input 
Filter. 

Message-filter  code  passed  to  the  message-filter  hook.  This  can  be  one  of  the  standard  MSGF_* 
values  (see  MsgFilterHook)  or  an  application-specific  value. 


Returns 

Message-filter  hook  return  indicator: 

TRUE  A message-filter  hook  returns  TRUE 

FALSE  All  message-filter  hooks  return  FALSE,  or  no  message-filter  hooks  are  defined. 

Remarks 

This  function  allows  an  application  to  pass  a message  to  the  message-filter  hook  procedure(s). 


Related  Functions 

• WinReleaseHook 

• WinSetHook 
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WinCallMsgFilter  - 
Call  Message  Filter 


Example  Code 

This  example  calls  a message  filter  hook  and  passes  a WM  CLOSE  message  in  message  box  mode. 


fdefine  INCL_WINH00KS  /*  Window  Hook  Functions 

linclude  <os2.h> 


BOOL  fHookRet; 
HAB  hab; 

QMSG  pqmsgpqmsg ; 

ULONG  ul  Filter; 


/*  filter  hook  return  indicator 
/*  Anchor-block  handle 
/*  Message  to  be  passed  to  the 
message-filter  hook 
/*  Filter 


POINTL  ptrPos  = {5L,5L};/*  pointer  position 


/*  initialize  message  structure  */ 


pqmsgpqmsg . hwnd 
pqmsgpqmsg. msg 
pqmsgpqmsg. mpl 
pqmsgpqmsg. mp2 
pqmsgpqmsg. time 
pqmsgpqmsg.pt! 


= HWND_DESKTOP; 
= WM_CL0SE; 

= MPVOID; 

= MPVOID; 

= OL; 

= ptrPos; 


/*  call  hook  in  message  box  mode  */ 
ul Filter  = MSGF_MESSAGEBOX; 

fHookRet  = WinCallMsgFilter(hab,  &pqmsgpqmsg,  ulFilter); 


*/ 


*/ 

*/ 

*/ 

*/ 

*/ 
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WinCancelShutdown 
Cancel  Shutdown 


#define  INCL_WINMESSAGEMGR  /*  Or  use  INCLWIN  or  INCL_PM.  Also  in  COMMON  section  */ 


BOOL  WinCancelShutdown  (HMQ  hmq,  BOOL  ICancelAlways) 


This  function  cancels  a request  for  an  application  to  shut  down. 


Parameters 

hmq  (HMQ)  - input 

Handle  of  message  queue  for  current  thread. 

ICancelAlways  (BOOL)  - input 
Cancellation  control. 

TRUE  No  WMQUIT  message  should  be  placed  on  this  queue  during  system  shutdown. 

FALSE  The  applications  ignore  any  outstanding  WM  QUIT  messages  already  sent  to  it,  but  a 
message  should  be  sent  during  other  system  shutdowns. 

Returns 

Success  indicator. 

TRUE  Successful  completion 
FALSE  Error  occurred. 

Remarks 

On  a system  shutdown,  each  message  queue  is  normally  posted  a WM  QUIT  message.  An 
application  can  process  this  message  in  one  of  two  ways: 

* Destroy  its  message  queue  using  WinDestroyMsgQueue  (hmq)  or, 

• Call  WinCancelShutdown  (hmq,  FALSE) 

Either  way  the  system  can  proceed  to  the  next  queue. 

If  the  application  determines  that  it  never  wants  a message  queue  to  receive  a WM  QUIT  message  as 
a result  of  a system  shutdown,  it  should  call  WinCancelShutdown  (hmq,  TRUE),  typically  right  after 
creating  the  message  queue. 


Related  Functions 

• WinTerminate 

• WinCreateMsgQueue 

• Winlnitialize 

• WinTerminate 


Related  Messages 

• WM  QUIT 
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WlnCancelShutdown  - 
Cancel  Shutdown 


Example  Code 

This  example  cancels  a shutdown  request  (WMQUIT  message)  and  specifies  that  the  message 
queue  will  not  accept  any  new  WM  QUIT  messages. 

Idefine  INCL_WINMESSAGEMGR  /*  Window  Message  Functions  */ 
linclude  <os2.h> 

HAB  hab, 

BOOL  f Success;  /*  Success  indicator  */ 

HMQ  hmq;  /*  queue  handle  */ 

hmq  = WinCreateMsgQueue(hab,  0); 
fSuccess  = WinCancel Shutdown (hmq,  TRUE); 
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WinChangeSwitchEntry 
Change  Switch  Entry 


#define  INCL_WINSWITCHLIST  /*  Or  use  INCL_WIN  or  INCL_PM  */ 


ULONG  WinChangeSwitchEntry  (HSWITCH  hswItchSwItch,  PSWCNTRL  pswctlSwItchData) 


This  function  changes  the  information  in  a Window  List  entry. 

Parameters 

hswItchSwItch  (HSWITCH)  - input 

Handle  to  the  Window  List  entry  to  be  changed. 

pswctlSwItchData  (PSWCNTRL)  - input 
Switch-control  data. 

Contains  the  information  to  change  the  Window  List  entry. 

If  the  idProcess  field  of  the  SWCNTRL  structure  is  0,  the  current  process  ID  is  used. 

If  the  idSession  field  of  the  SWCNTRL  structure  is  0,  the  current  session  ID  is  used. 

Returns 

Return  code: 

0 Successful  completion 
Other  Error  occurred. 

Possible  returns  from  WinGetLastError 

PMERRINVALIDSWITCHHANDLE  An  invalid  Window  List  entry  handle  was  specified. 

PMERR_INVALID_WINDOW  The  window  specified  with  a Window  List  function  is  not  a 

valid  frame  window. 

Remarks 

Leading  and  trailing  blanks  are  removed  from  the  title  and,  if  necessary,  it  is  truncated  to  60 
characters. 
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WinChangeSwitchEntry  - 
Change  Switch  Entry 


Example  Code 

This  example  changes  the  program  name  of  a task-list  entry  to  'Generic:  NEW.APP'  using  the  handle 
returned  by  WinAddSwitchEntry. 


fdefine  INCL_WINSWITCHLIST  /*  Window  Switch  List  Functions  */ 


Idefine  INCL_WINWINDOWMGR  /*  Window  Manager  Functions  */ 
linclude  <os2.h> 

HSWITCH  hswitch;  /*  task-list  entry  handle  */ 
SWCNTRL  swctl ; /*  switch-control  data  */ 
PID  pid;  /*  process  id  */ 
HAB  hab;  /*  anchor-block  handle  */ 
HWND  hwndFrame;  /*  frame  handle  */ 


hab  = WinQueryAnchorBlock(hwndFrame) ; /*  gets  anchor  block  */ 

WinQueryWindowProcess(hwndFrame,  &pid,  NULL);/*  gets  process  id  */ 


/*  initialize  switch  structure  */ 
swctl. hwnd  = hwndFrame; 
swctl .hwndlcon  = NULLHANDLE; 
swctl. hprog  = NULLHANDLE; 
swctl .idProcess  = pid; 
swctl .idSession  = 0; 
swctl . uchVi s i bi 1 i ty  = SWL_VISIBLE; 
swctl. fbJump  = SWL_JUMPABLE; 
swctl  .szSwtitle[0]=  0; 


/*  window  handle  */ 
/*  icon  handle  */ 
/*  program  handle  */ 
/*  process  identifier  */ 
/*  session  identifier  */ 
/*  visibility  */ 
/*  jump  indicator  */ 
/*  program  name  */ 


hswitch  = WinCreateSwitchEntry(hab,  &swctl); 


/*  set  application  name  */ 

strcpy(swctl .szSwtitle,  "Generic:  NEW.APP"); 

WinChangeSwitchEntry(hswitch,  &swctl) ; 
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WinCheckButton  - 
Set  Checkstate  of  Button 


#define  INCL_WINWINDOWMGR  /*  Or  use  INCL_WIN  or  INCL_PM  */ 


USHORT  WinCheckButton  (HWND  hwndDIg,  USHORT  usld,  USHORT  usChkstate) 


This  macro  sets  the  checked  state  of  the  specified  button  control.  It  returns  the  previous  check  state. 


Parameters 

hwndDIg  (HWND)  - input 
Dialog  window  handle. 

usld  (USHORT)  - input 
Button  control  identity. 

usChkstate  (USHORT)  - input 

Indicates  the  current  checked  state  of  the  button. 


Returns 

Returns  the  previous  checkstate. 


Remarks 

This  macro  expands  to: 

fdefine  WinCheckButton (hwndDIg,  usld,  usChkstate) 

( (USHORT) Wi nSendDl gl temMsg ( hwndDl g , 

usld, 

BM_SETCHECK, 

MPFROMSHORT (usChkstate), 
(MPARAM)NULL)) 

This  call  requires  the  existence  of  a message  queue. 


Related  Functions 

• WinSendDIgltemMsg 


Related  Messages 

• BM  SETCHECK 
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WinCheckButton  - 
Set  Checkstate  of  Button 


Example  Code 

This  example  responds  to  a button  click  (BN_CLICKED,  WM  CONTROL  message)  on  a check  box  by 
setting  the  checked  state  of  the  button. 

Idefine  INCL_WINWINDOWMGR  /*  Window  Manager  Functions  */ 

Idefine  INCL_WINBUTTONS  /*  Window  Button  definitions  */ 

linclude  <os2.h> 

USHORT  usCheckld;  /*  check  box  id  */ 

HWND  hwndDlg;  /*  dialog  window  handle  */ 

USHORT  usChkstate;  /*  new  checked  state  */ 

USHORT  usOldstate;  /*  old  checked  state  */ 

MPARAM  mpl;  /*  Parameter  1 (recti  structure)  */ 

MPARAM  mp2;  /*  Parameter  2 (frame  boolean)  */ 

case  WM_C0NTR0L: 

/*  switch  on  control  code  */ 
switch(SH0RT2FR0MMP(mpl)) 

{ 

case  BN_CLICKED: 

usCheckld  = SHORTlFROMMP(mpl) ; 

/*  query  current  check  state  */ 
usChkstate  = WinQueryButtonCheckstate( hwndDlg, 
usCheckld) ; 

/*  set  box  check  state  */ 

usOldstate  = WinCheckButton(hwndDlg,  usCheckld, 

usChkstate) ; 

break; 

} 
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WinCheckMenultem 
Check  Menu  Item 


#define  INCL_WINWINDOWMGR  /*  Or  use  INCL_WIN  or  INCL_PM  */ 


BOOL  WinCheckMenultem  (HWND  hwndMenu,  USHORT  usld,  BOOL  fCheck) 


This  macro  sets  the  check  state  of  the  specified  menu  item  to  the  flag. 


Parameters 

hwndMenu  (HWND)  - input 
Menu  window  handle. 

usld  (USHORT)  - input 
Item  identifier. 

fCheck  (BOOL)  - input 
Check  flag. 


Returns 

Success  indicator: 

TRUE  Successful  completion 
FALSE  Error  occurred. 

Remarks 

This  macro  expands  to: 

fdefine  WinCheckMenuItem(hwndMenu,  usld,  fCheck) 

((BOOL)WinSendMsg(hwndMenu, 

MMSETITEMATTR, 

MPFR0M2SH0RT (usld,  TRUE), 

MPFR0M2SH0RT(MIA_CHECKED,  (BOOL) (fCheck)  ? MIA_CHECKED  : 0))) 
This  function  requires  the  existence  of  a message  queue. 


Related  Functions 

• WinSendMsg 

Related  Messages 

• MM_SETITEMATTR 


8-32  PM  Programming  Reference 


WinCheckMenultem  - 
Check  Menu  Item 


Example  Code 

This  example  responds  to  a select  menu  message  (WM  MENUSELECT)  by  querying  (via 
WinlsMenultemChecked)  the  check  attribute  and  then  setting  the  check  state  of  the  menu  item  that 
was  selected. 


fdefine  INCL_WINWINDOWMGR  /*  Window  Manager  Functions  */ 

linclude  <os2.h> 


USHORT  usltemld; 
HWND  hwndMenu; 
BOOL  usChkstate; 
BOOL  fSuccess; 
MPARAM  mpl; 

MPARAM  mp2; 


/*  menu  item  id 

/*  menu  handle 

/*  new  checked  state 

/*  success  indicator 

/*  Parameter  1 (menu  item  id) 

/*  Parameter  2 (menu  handle) 


case  WMJOUSELECT: 

usltemld  = SHORTlFROMMP(mpl) ; 
hwndMenu  = HWNDFR0MMP(mp2) ; 


*/ 

*/ 

*/ 

*/ 

*/ 

*/ 


/*  query  current  check  state  */ 

usChkstate  = WinIsMenuItemChecked(hwndMenu,  usltemld); 


/*  set  menu  item  check  state  */ 

fSuccess  = WinCheckMenuItem(hwndMenu,  usltemld,  ! usChkstate); 
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WinCloseClipbrd 
Close  Clipboard 


#define  INCL_WINCLIPBOARD  /*  Or  use  INCL_WIN  or  INCL_PM  */ 


BOOL  WinCloseClipbrd  (HAB  hab) 


This  function  closes  the  clipboard,  allowing  other  applications  to  open  it  with  the  WinOpenClipbrd 
function. 

Parameters 

hab  (HAB)  - input 

Anchor-block  handle. 


Returns 

Success  indicator: 

TRUE  Successful  completion 
FALSE  Error  occurred. 

Remarks 

This  function  causes  the  contents  of  the  clipboard  to  be  drawn  in  the  clipboard  viewer  window  (if 
any),  by  sending  it  a WM  DRAWCLIPBOARD  message.  This  action  occurs  only  if  the  clipboard  data 
has  changed. 

The  clipboard  must  be  open  before  this  function  is  invoked. 


Related  Functions 

• WinEmptyClipbrd 

• WinEnumClipbrdFmts 

• WinOpenClipbrd 

• WinQueryClipbrdData 

• WinQueryClipbrdFmtlnfo 

• WinQueryClipbrdOwner 

• WinQueryClipbrdViewer 

• WinSetClipbrdData 

• WinSetClipbrdOwner 

• WinSetClipbrdViewer 

Related  Messages 

• WM_DRAWCLIPBOARD 

Example  Code 

This  example  closes  the  clipboard,  previously  opened  by  WinOpenClipbrd,  to  allow  other 
applications  to  open  it  for  use. 

Idefine  INCL_WINCLIPBOARD  /*  Window  Clipboard  Functions  */ 

linclude  <os2.h> 

BOOL  fSuccess;  /*  success  indicator  */ 

HAB  hab;  /*  anchor-block  handle  */ 

fSuccess  = WinCloseCl ipbrd(hab) ; 
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WinCompareStrings  - 
Compare  Strings 


#define  INCL_WINCOUNTRY  /*  Or  use  INCL_WIN  or  INCL_PM  */ 


ULONG  WinCompareStrings  (HAB  hab,  ULONG  IdCodepage,  ULONG  IdCountryCode, 

PSZ  pszStrlngl,  PSZ  pszString2,  ULONG  fiOptions) 


Compares  two  null-terminated  strings  defined  using  the  same  code  page. 


Parameters 

hab  (HAB)  - input 

Anchor-block  handle. 

IdCodepage  (ULONG)  - input 

Code  page  identity  of  both  strings. 

IdCountryCode  (ULONG)  - input 
Country  code. 

pszStrlngl  (PSZ)  - input 
String  1. 

pszString2  (PSZ)  - input 
String  2. 

fiOptions  (ULONG)  - input 
Reserved. 

0 Reserved  value. 

Returns 

Comparison  result: 

WCS_EQ  Strings  are  equal 

WCS_LT  String  1 is  less  than  string  2 

WCS_GT  String  1 is  greater  than  string  2 

WCSERROR  Error  occurred. 

Possible  returns  from  WinGetLastError 

PMERR  INVALID  STRING  PARM  The  specified  string  parameter  is  invalid. 

Related  Functions 

• WinLoadString 

• WinNextChar 

• WinPrevChar 

• WinSubstituteStrings 

• WinUpper 

• WinUpperChar 
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WinCompareStrings  - 
Compare  Strings 

Example  Code 

This  example  compares  two  strings  using  the  same  code  page:  the  first  string  is  loaded  from  a 
resource  DLL,  while  the  second  is  created  by  the  application. 

fdefine  INCL_WINCOUNTRY  /*  Window  Country  Functions  */ 

fdefine  INCL_WINWINDOWMGR  /*  Window  Manager  Functions  */ 

fdefine  INCL_DOSMODULEMGR  /*  Module  Manager  Functions  */ 

finclude  <os2.h> 

ULONG  ul Result;  /*  comparison  result  */ 

HAB  hab;  /*  anchor-block  handle  */ 

ULONG  idCodepage=437;  /*  Code  page  identity  of  both  strings  */ 

ULONG  idCountryCode=l;/*  Country  code  */ 

char  pszStringl[10] ; /*  first  string  */ 

char  pszString2[10] ; /*  second  string  */ 

LONG  1 Length;  /*  length  of  string  */ 

ULONG  idString  = STRING_ID;  /*  String  identifier  */ 

LONG  lBufferMax  = 10;/*  Size  of  buffer  */ 

HMODULE  hmodDLL;  /*  Handle  of  the  module  which  contains 

the  help  table  and  help  subtable 
resources.  */ 

CHAR  LoadError[100] ; /*  object  name  buffer  for  DosLoad  */ 

ULONG  rc;  /*  return  code  */ 

/*  obtain  resource  handle  */ 

rc  = DosLoadModule(LoadError,  sizeof(LoadError) , "RES. DLL", 

&hmodDLL) ; 

/*  load  string  from  resource  */ 
if  (rc  ==  0) 

1 Length  = WinLoadString(hab,  hmodDLL,  idString,  lBufferMax, 

pszStringl) ; 

/*  compare  strings  */ 
if  (1  Length  > 0) 

{ 

/*  set  second  string  */ 
strcpy(pszString2, "Compare") ; 

ulResult  = WinCompareStrings (hab,  idCodepage,  idCountryCode, 

pszStringl,  pszString2,  0); 

} 
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WinCopyAccelTable  - 
Copy  Accelerator  Table 


#define  INCL_WINACCELERATORS  /*  Or  use  INCL_WIN  or  INCL_PM  */ 


ULONG  WinCopyAccelTable  (HACCEL  hAccel,  PACCELTABLE  pacctAccelTable, 

ULONG  ulCopyMax) 


This  function  is  used  to  get  the  accelerator-table  data  corresponding  to  an  accelerator-table  handle, 
or  to  determine  the  size  of  the  accelerator-table  data. 

Parameters 

hAccel  (HACCEL)  - input 
Accelerator-table  handle. 

pacctAccelTable  (PACCELTABLE)  - input/output 
Accelerator-table  data  area: 

NULL  Return  the  size,  in  bytes,  of  the  complete  accelerator  table,  and  ignore  the  ulCopyMax 
parameter. 

Other  Copy  up  to  ulCopyMax  bytes  of  the  accelerator  table  into  this  data  area. 

ulCopyMax  (ULONG)  - input 
Maximum  data  area  size. 


Returns 

Amount  copied  or  size  required: 

Other  Amount  of  data  copied  into  the  data  area,  or  the  size  of  data  area  required  for  the 
complete  accelerator  table. 

0 Error  occurred. 

Possible  returns  from  WinGetLastError 

PMERR  INVALID  HACCEL  An  invalid  accelerator-table  handle  was  specified. 

Related  Functions 

• WinCreateAccelTable 

• WinDestroyAccelTable 

• WinLoadAccelTable 

• WinQueryAccelTable 

• W inSet  AccelTable 

• WinTranslateAccel 


Chapter  8.  Window  Functions  8-37 


W inCopy AccelTable  - 
Copy  Accelerator  Table 


Example  Code 

This  example  gets  the  accelerator-table  data  corresponding  to  an  accelerator-table  handle  returned 
by  WinCreateAccelTable  or  WinLoadAccelTable  and  assigns  the  accelerator  table  code  page  to  a 
variable. 

fdefine  INCL_WINACCELERATORS  /*  Window  Accelerator  Functions  */ 
linclude  <os2.h> 


ULONG  ul Copied;  /*  bytes  copied  */ 
HACCEL  hAccel ; /*  Accelerator-table  handle  */ 
ACCELTABLE  pacctAccel Table;/*  Accelerator-table  data  area  */ 
ULONG  ulCopyMax;  /*  Maximum  data  area  size  */ 
ULONG  ul Accel  CP;  /*  code  page  */ 


ulCopyMax  = sizeof(pacctAccelTable); 
if  (hAccel) 

ulCopied  = WinCopyAccelTable(hAccel , &pacctAccel Table, 

ulCopyMax) ; 

if  (ulCopied) 

ulAccelCP  = pacctAccel Table. codepage; 
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WinCopyRect  - 
Copy  Rectangle 


#define  INCL_WINRECTANGLES  /*  Or  use  INCL_WIN  or  INCL_PM  */ 


BOOL  WinCopyRect  (HAB  hab,  PRECTL  prclDest,  PRECTL  prcISrc) 


This  function  copies  a rectangle  from  prcISrc  to  prclDest. 


Parameters 

hab  (HAB)  - input 

Anchor-block  handle. 

prclDest  (PRECTL)  - output 
Destination  rectangle. 

Note:  The  value  of  each  field  in  this  structure  must  be  in  the  range  —32  768  through  32  767.  The 
datatype  WRECT  can  also  be  used,  if  supported  by  the  language. 

prcISrc  (PRECTL)  - input 
Source  rectangle. 

Note:  The  value  of  each  field  in  this  structure  must  be  in  the  range  -32  768  through  32  767.  The 
datatype  WRECT  can  also  be  used,  if  supported  by  the  language. 

Returns 

Success  indicator: 

TRUE  Successful  completion 
FALSE  Error  occurred. 

Related  Functions 

• WinEqualRect 

• WinFillRect 

• WinlnflateRect 

• WinlntersectRect 

• WinlsRectEmpty 

• WinOffsetRect 

• WinPtlnRect 

• WinSetRect 

• WinSetRectEmpty 

• WinSubtractRect 

• WinUnionRect 

Example  Code 

This  example  copies  a rectangle  using  WinCopyRect. 

fdefine  INCL_WINRECT ANGLES  /*  Window  Rectangle  Functions  */ 

linclude  <os2.h> 


BOOL  fSuccess;  /*  success  indicator  */ 
HAB  hab;  /*  anchor-block  handle  */ 
RECTL  prclRect2  = {0,0,200,200};  /*  source  rectangle  */ 
RECTL  prcl Recti;  /*  destination  rectangle  */ 


fSuccess  = WinCopyRect (hab,  &prcl Recti,  &prclRect2); 
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WinCpTranslateChar  - 
Translate  Character  with  Code  Page 


#define  INCL_WINCOUNTRY  /*  Or  use  INCL_WIN  or  INCL_PM  */ 


UCHAR  WinCpTranslateChar  (HAB  hab,  ULONG  IdCpSource,  UCHAR  ucSource, 

ULONG  idCpDest) 


This  function  translates  a character  from  one  code  page  to  another. 

Parameters 

hab  (HAB)  - input 

Anchor-block  handle. 

IdCpSource  (ULONG)  - input 
Source-character  code  page. 

ucSource  (UCHAR)  - input 
Character  to  be  translated. 

IdCpDest  (ULONG)  - input 

Code  page  of  the  resultant  character. 


Returns 

If  nonzero,  the  translated  or  substitution  (X‘FF‘)  character. 

Possible  returns  from  WinGetLastError 

PMERRINVALIDSTRINGPARM  The  specified  string  parameter  is  invalid. 

PMERR_INVALID_SRC_CODEPAGE  The  source  code  page  parameter  is  invalid. 

PMERR_INVALID_DST_CODEPAGE  The  destination  code  page  parameter  is  invalid. 

Remarks 

Successful  invocation  of  this  function  indicates  that  either  (1)  the  character  was  directly  mapped  into 
the  destination  code  page  or,  (2)  the  substitution  character  (X 1 FF ‘ ) was  returned. 

See  the  WinQueryCpList  function  for  Code  Page  acceptable  in  this  function. 


Related  Functions 

• WinCpTranslateString 

• WinQueryCp 

• WinQueryCpList 

• WinSetCp 
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WinCpTranslateChar  - 
Translate  Character  with  Code  Page 


Example  Code 

This  example  translates  a character  from  US  code  page  437  to  multilingual  code  page  850. 


Idefine  INCL_WINCOUNTRY  /*  Window  Country  Functions  */ 
linclude  <os2.h> 

HAB  hab;  /*  anchor-block  handle  */ 
UCHAR  ucDest;  /*  translated  character  */ 
UCHAR  ucSource  = 'A';  /*  source  character  */ 


ULONG  idCpSource=437;  /*  Code  page  of  source  character  (US)  */ 

ULONG  idCpDest=850;  /*  Code  page  of  dest.  character  (multi)  */ 

ucDest  = WinCpTranslateChar(hab,  idCpSource,  ucSource,  idCpDest); 
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WinCpTranslateString  - 
Translate  String  with  Code  Page 


#define  INCL_WINCOUNTRY  /*  Or  use  INCL_WIN  or  INCL_PM  */ 


BOOL  WinCpTranslateString  (HAB  hab,  ULONG  IdCpSource,  PSZ  pszSource, 

ULONG  IdCpDest,  ULONG  cbLenDest,  PSZ  pszDest) 


This  function  translates  a string  from  one  code  page  to  another. 


Parameters 

hab  (HAB)  - input 

Anchor-block  handle. 

IdCpSource  (ULONG)  - input 
Source-string  code  page. 

pszSource  (PSZ)  - input 
String  to  be  translated. 

This  is  a null-terminated  string. 

IdCpDest  (ULONG)  - input 

Code  page  of  the  resultant  string. 

cbLenDest  (ULONG)  - input 

Maximum  length  of  output  string. 

An  error  is  raised  if  this  is  not  large  enough  to  contain  the  translated  string. 

pszDest  (PSZ)  - output 
The  translated  string. 

This  is  a null-terminated  string. 


Returns 

Success  indicator: 

TRUE  Successful  completion 
FALSE  Error  occurred. 


Possible  returns  from  WinGetLastError 

PMERRINVALIDSTRINGPARM 

PMERRINVALIDSRCCODEPAGE 

PMERRINVALIDDSTCODEPAGE 

PMERRPARAMETEROUTOFRANGE 


The  specified  string  parameter  is  invalid. 

The  source  code  page  parameter  is  invalid. 

The  destination  code  page  parameter  is  invalid. 

The  value  of  a parameter  was  not  within  the  defined  valid 
range  for  that  parameter. 


Remarks 

Successful  invocation  of  this  function  indicates  that  either  (1)  the  character  was  directly  mapped  into 
the  destination  code  page  or,  (2)  the  substitution  character  (X'FF1)  was  returned. 

See  the  WinQueryCpList  function  for  Code  Pages  acceptable  in  this  function. 
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WinCpTranslateString  - 
Translate  String  with  Code  Page 


Related  Functions 

• WinCpTranslateChar 

• WinQueryCp 

• WinQueryCpList 

• WinSetCp 

Example  Code 

This  example  translates  a string  from  US  code  page  437  to  multilingual  code  page  850. 

Idefine  INCL_WINCOUNTRY  /*  Window  Country  Functions  */ 

finclude  <os2.h> 

HAB  hab;  /*  anchor-block  handle  */ 

ULONG  idCpSource=437;  /*  Code  page  of  source  character  (US)  */ 

ULONG  idCpDest=850;  /*  Code  page  of  dest.  character  (multi)  */ 

char  pszSource[10] ; /*  source  string  */ 

char  pszDest[10];  /*  destination  string  */ 

ULONG  cbLenDest  = 9L;  /*  max  length  of  destination  string  */ 

BOOL  f Success; 

s t rcpy (ps  zSource TRANS  LATE ") ; 

fSuccess  = WinCpTranslateString(hab,  idCpSource,  pszSource, 

idCpDest,  cbLenDest,  pszDest); 
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W in C reate AccelTable  - 
Create  Accelerator  Table 


#define  INCL_WINACCELERATORS  /*  Or  use  INCL_WIN  or  INCL_PM  */ 


HACCEL  WlnCreateAccelT able  (HAB  hab,  PACCELTABLE  pacctAccelTable) 


This  function  creates  an  accelerator  table  from  the  accelerator  definitions  in  memory. 


Parameters 

hab  (HAB)  - input 

Anchor-block  handle. 

pacctAccelTable  (PACCELTABLE)  - input 
Accelerator  table. 


Returns 

Accelerator-table  handle. 

Remarks 

This  function  returns  a different  hAccel  value  when  called  twice  in  succession  with  the  same 
parameter  values. 

Related  Functions 

• WinCopy  AccelTable 

• WinDestroyAccelTable 

• WinLoadAccelTable 

• WinQueryAccelTable 

• WinSetAccelTable 

• WinTranslateAccel 
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WinC reate AccelTable  - 
Create  Accelerator  Table 


Example  Code 

This  example  creates  an  accelerator-table  handle  for  an  in  memory  accelerator  table  consisting  of  3 
accelerator  keys,  using  US  codepage  437. 

Idefine  INCL_WINACCELERATORS  /*  Window  Accelerator  Functions  */ 


Idefine  INCL_WININPUT  /*  Key  constants  */ 
Idefine  INCL_WINFRAMEMGR  /*  Frame  control  constants  */ 
linclude  <os2.h> 

HACCEL  hAccel;  /*  Accelerator-table  handle  */ 
ACCELTABLE  pacctAccelTable;/*  Accelerator-table  data  area  */ 
HAB  hab;  /*  anchor-block  handle  */ 
/*  in  memory  accelerator  table  */ 

ACCEL  acctable[]  = { 


AF_SYSCOMMAND  | AF_ALT  | AF_VIRTUALKEY,VK_F4,SC_CL0SE, 
AF  SYSCOMMAND  | AF  ALT  | AF_VIRTUALKEY,VK_F7,SC  MOVE, 
AF_SYSCOMMAND  | AF_ALT  | AF_VIRTUALKEY,VK_F8,SC_SIZE}; 

/*  initialize  accelerator  table  structure,  including  in  memory 
accelerator  table  */ 
pacctAccelTable. cAccel  = 3; 
pacctAccelTable. codepage  = 437; 
pacctAccelTable.aaccel  [0]  = acctable[0]; 

hAccel  = WinCreateAccelTable(hab,  &pacctAccel Table) ; 
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WinCreateAtomT  able 
Create  Atom  Table 


#define  INCL_WINATOM  /*  Or  use  INCL_WIN  or  INCL_PM  */ 


HATOMTBL  WinCreateAtomTable  (ULONG  ullnitlal,  ULONG  ulBuckets) 


This  function  creates  an  empty  atom  table  of  the  specified  size. 


Parameters 

ullnitlal  (ULONG)  - input 
Initial  bytes. 

Initial  number  of  bytes  to  be  reserved  for  the  atom  table.  This  is  a lower  bound  on  the  amount  of 
memory  reserved.  The  amount  of  memory  actually  used  by  an  atom  table  depends  upon  the 
actual  number  of  atoms  stored  in  the  table.  If  zero,  the  size  of  the  atom  table  is  the  minimum 
size  needed  to  store  the  atom  hash  table. 

ulBuckets  (ULONG)  - input 
Size  of  the  hash  table. 

Used  to  access  atoms.  If  zero,  the  default  value  of  37  is  used.  The  best  results  are  achieved  if  a 
prime  number  is  used. 


Returns 

Atom-table  handle: 

NULLHANDLE  Call  failed. 

Other  Atom-table  handle.  This  must  be  passed  as  a parameter  in  subsequent  atom 

manager  calls. 


Remarks 

The  minimum  size  of  atom  table  allocated  is  16+  (2*ul Buckets). 

The  atom  table  is  owned  by  the  process  from  which  this  function  is  issued.  It  cannot  be  accessed 
directly  from  any  other  process.  If  it  is  still  in  existence  when  the  process  terminates,  it  will 
automatically  be  deleted  by  the  system. 

There  is  a system  atom  table  which  is  created  at  boot  time,  which  cannot  be  destroyed,  and  which 
can  be  accessed  by  any  process  in  the  system.  The  handle  of  the  system  atom  table  is  queried  with 
the  WinQuerySystemAtomTable  function. 


Related  Functions 

• WinAddAtom 

• WinDeleteAtom 

• WinDestroyAtomTable 

• WinFindAtom 

• WinQueryAtomLength 

• WinQueryAtomName 

• WinQueryAtomUsage 

• WinQuerySystemAtomTable 
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WinC reate AtomTable  - 
Create  Atom  Table 


Example  Code 

This  example  creates  an  Atom  Table  of  default  size,  adds  the  atom  'newatom'  to  the  new  table,  and 
then  destroys  the  table. 


fdefine  INCL_WINATOM  /*  Window  Atom  Functions  */ 
linclude  <os2.h> 

ATOM  atom;  /*  new  atom  value  */ 
HATOMTBL  hatomtbl AtomTbl ; /*  atom-table  handle  */ 
HATOMTBL  hatomtbl Destroy;  /*  result  of  destroy  table  */ 
char  pszAtomName[10] ; /*  atom  name  */ 


ULONG  ul Initial  = 0;  /*  initial  atom  table  size  (use  default)*/ 

ULONG  ulBuckets  = 0;  /*  size  of  hash  table  (use  default)  */ 

/*  create  atom  table  of  default  size  */ 

hatomtbl AtomTbl  = WinCreateAtomTable(ul Initial , ulBuckets); 

/*  define  name  for  new  atom  and  add  to  table  */ 

s t rcpy ( p s zAtomName ," newatom" ) ; 

atom  = Wi nAddAtom( hatomtbl AtomTbl , pszAtomName) ; 

hatomtbl Destroy  = WinDestroyAtomTable(hatomtblAtomTbl); 
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WinCreateCursor 
Create  Cursor 


#define  INCL_WINCURSORS  /*  Or  use  INCL_WIN  or  INCL_PM.  Also  in  COMMON  section  */ 


BOOL  WinCreateCursor  (HWND  hwnd,  LONG  lx,  LONG  ly,  LONG  lex,  LONG  Icy,  ULONG  ulrgf, 
PRECTL  prcICIIp) 


This  function  creates  or  changes  a cursor  for  a specified  window. 


Parameters 

hwnd  (HWND)  - input 

Handle  of  window  in  which  cursor  is  displayed. 

This  must  be  the  handle  of  a window  for  which  the  application  can  receive  input. 

lx  (LONG)  - input 

x-position  of  cursor. 


ly(LONG)  - input 

y-position  of  cursor. 

lex  (LONG)  - input 
x-size  of  cursor. 

If  0,  the  system  nominal  border  width  (SV_CXBORDER)  is  used. 

Icy  (LONG)  - input 
y-size  of  cursor. 

If  0,  the  system  nominal  border  height  (SV_CYBORDER)  is  used. 

ulrgf  (ULONG)  - input 

Controls  the  appearance  of  the  cursor: 


CURSOR_SOLID  The  cursor  is  solid. 

CURSOR_HALFTONE  The  cursor  is  halftone. 


CURSOR_FRAME  The  cursor  is  a rectangular  frame. 

CURSOR_FLASH  The  cursor  flashes. 

CURSOR_SETPOS  Set  a new  cursor  position,  lex  and  Icy  are  ignored.  Used  when  a cursor 
has  already  been  created.  In  this  case,  all  other  appearance  flags  are 
ignored. 


prcICIIp  (PRECTL)  - input 
Cursor  rectangle. 


A rectangle  within  which  the  cursor  is  visible.  If  the  cursor  goes  outside  this  rectangle,  it  is 
clipped  away  and  is  invisible. 


The  rectangle  is  specified  in  window  coordinates. 

If  prcIClip  is  NULL,  the  drawing  of  the  cursor  is  clipped  to  the  window  rectangle  of  hwnd. 

Note:  The  cursor  is  always  clipped  to  the  window  rectangle,  even  If  part  of  prcIClip  is  outside  it. 

The  value  of  each  field  in  this  structure  must  be  in  the  range  —32  768  through  32  767.  The 
datatype  WRECT  can  also  be  used,  If  supported  by  the  language. 
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Create  Cursor 


Returns 

Success  indicator: 

TRUE  Successful  completion 
FALSE  Error  occurred. 

Possible  returns  from  WinGetLastError 

PMERR  INVALID  HWND  An  invalid  window  handle  was  specified. 

PMERRJNVALID_FLAG  An  invalid  bit  was  set  for  a parameter.  Use  constants 

defined  by  PM  for  options,  and  do  not  set  any  reserved 
bits. 


Remarks 

The  cursor  is  used  to  indicate  the  position  of  text  input.  It  is  initially  hidden  and  must  be  made 
visible  using  the  WinShowCursor  function. 

This  function  destroys  any  existing  cursor,  as  it  is  confusing  to  the  user  if  two  cursors  are  visible  at 
any  one  time.  An  application  creates  and  displays  a cursor  when  it  has  the  input  focus,  or  is  the 
active  window.  Creating  a cursor  at  any  other  time  can  stop  the  cursor  from  flashing  in  another 
window.  Similarly,  when  the  application  loses  the  input  focus  or  becomes  inactive,  it  destroys  its 
cursor  using  the  WinDestroyCursor  function. 

The  cursor  width  is  generally  specified  as  0 (nominal  border  width  is  used).  This  is  preferable  to  a 
value  of  1,  for  example,  as  such  a fine  width  is  almost  invisible  on  a high-resolution  device. 


Related  Functions 

• WinDestroyCursor 

• WinQueryCursorlnfo 

• WinShowCursor 

Example  Code 

This  example  creates  a cursor  of  default  height  and  width  at  (0,200)  which  will  be  visible  within  the 
entirety  of  the  input  window. 


fdefine  INCL_WINCURSORS  /*  Window  Cursor  Functions  */ 

finclude  <os2.h> 


BOOL 

fSuccess; 

/* 

success  indicator 

*/ 

HWND 

hwnd; 

/* 

cursor  display  window 

*/ 

LONG 

lx  = 0; 

/* 

cursor  x position 

*/ 

LONG 

ly  = 200; 

/* 

cursor  y position 

*/ 

UL0NG 

ul  rgf; 

/* 

cursor  appearance 

*/ 

fSuccess  = WinCreateCursor(hwnd,  lx,  ly,  0,  0,  ulrgf,  NULL); 
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WinCreateDIg 
Create  Dialog 


#define  INCL_WINDIALOGS  /*  Or  use  INCL_WIN  or  INCL_PM  */ 


HWND  WinCreateDIg  (HWND  hwndParent,  HWND  hwndOwner,  PFNWP  pDIgProc, 
PDLGTEM  PLATE  pdlgtDIgTmp,  PVOID  pCreateParams) 


This  function  creates  a dialog  window. 


Parameters 

hwndParent  (HWND)  - input 

Parent-window  handle  of  the  created  dialog  window: 

HWND_DESKTOP  The  desktop  window 

HWND_OBJECT  Object  window 

Other  Specified  window. 

hwndOwner  (HWND)  - input 

Requested  owner-window  handle  of  the  created  dialog  window. 

The  actual  owner  window  is  calculated  using  the  algorithm  specified  in  the  description  of  the 
WinLoadDIg  function. 

pDIgProc  (PFNWP)  - input 

Dialog  procedure  for  the  created  dialog  window. 

pdlgtDIgTmp  (PDLGTEMPLATE)  - input 
Dialog  template. 

pCreateParams  (PVOID)  - input 
Application-defined  data  area. 

This  is  passed  to  the  dialog  procedure  in  the  WMJNITDLG  message. 


Returns 

Dialog-window  handle: 

NULLHANDLE  Dialog  window  not  created 
Other  Dialog-window  handle. 


Possible  returns  from  WinGetLastError 

PMERRJNVALIDHWND 
P M E R R _ IN  V A LID  JNTEGE  R_  ATOM 
PMERRINVALIDATOMNAME 
PMERRATOMNAMENOTFOUND 


An  invalid  window  handle  was  specified. 

The  specified  atom  is  not  a valid  integer  atom. 

An  invalid  atom  name  string  was  passed. 

The  specified  atom  name  is  not  in  the  atom  table. 


Remarks 

This  function  is  identical  to  the  WinLoadDIg  call  except  that  it  creates  a dialog  window  from 
pdlgtDIgTmp  in  memory,  rather  than  a dialog  template  in  a resource  file. 

This  function  should  not  be  used  while  the  pointing  device  capture  is  set  (see  WinSetCapture). 
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WinCreateDIg  - 
Create  Dialog 


Related  Functions 

• WinDefDIgProc 

• WinDismissDIg 

• WinDIgBox 

• WinGetDIgMsg 

• WinLoadDIg 

• WinProcessDIg 

Related  Messages 

• WMJNITDLG 

Example  Code 

This  example  loads  a dialog  template  from  the  application's  resources  and  uses  the  template  with 
the  WinCreateDIg  function  to  create  a dialog  window.  This  example  is  identical  to  calling  the 
WinLoadDIg  function,  but  gives  the  application  the  advantage  of  reviewing  and  modifying  the  dialog 
template  before  creating  the  dialog  window. 

Idefine  INCL_WINDIALOGS  /*  Window  Dialog  Mgr  Functions  */ 

Idefine  INCL_DOSRESOURCES  /*  OS/2  Resource  functions  */ 

linclude  <os2.h> 

PFNWP  MyDlgProc; 

Idefine  ID_DIAL0G  1 

PDLGTEMPLATE  pdlgt;  /*  dialog  template  */ 

DosGetResource(GL,  RT_DIAL0G,  ID_DIAL0G,  (PVOID)pdlgt) ; 

/*  make  any  changes  to  dialog  template  here  */ 

Wi nCreateDl g (HWND_DESKTOP , 

NULLHANDLE,  /*  owner  window  */ 

MyDlgProc,  /*  address  of  dialog  procedure  */ 

pdlgt,  /*  address  of  dialog  structure  */ 

NULL);  /*  application-specific  data  */ 
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WinCreateFrameControls 
Create  Frame  Controls 


#define  INCL_WINFRAMEMGR  /*  Or  use  INCL_WIN  or  INCL_PM  */ 


BOOL  WinCreateFrameControls  (HWND  hwndFrame,  PFRAMECDATA  pFcdata,  PSZ  pszTitle) 


This  function  creates  the  standard  frame  controls  for  a specified  window. 


Parameters 

hwndFrame  (HWND)  - input 
Frame-window  handle. 

Becomes  the  parent  and  owner  window  of  all  the  frame  controls  that  are  created: 

HWND_DESKTOP  The  desktop  window 

HWND_OBJECT  Object  window 

Other  Specified  window. 

pFcdata  (FRAMECDATA)  - input 
Frame-control  data. 

This  includes  a combination  of  frame  creation  flags  (FCF_*),  that  specifies  which  frame  controls 
are  to  be  created.  For  further  information,  see  “Frame  Creation  Flags”  on  page  15-1. 

pszTitle  (PSZ)  - input 
Title  string. 

A string  that  is  displayed  in  the  WC_TITLEBAR  control  when  FCF_TITLEBAR  is  specified  in 
pFcdata. 


Returns 

Success  indicator: 

TRUE  Successful  completion 
FALSE  Error  occurred. 

Possible  returns  from  WinGetLastError 

PMERR  INVALID  HWND  An  invalid  window  handle  was  specified. 

PMERR_INVALID_FLAG  An  invalid  bit  was  set  for  a parameter.  Use  constants 

defined  by  PM  for  options,  and  do  not  set  any  reserved 
bits. 


Remarks 

This  function  is  typically  used  when  the  standard  frame  controls  are  needed  for  use  with  a 
nonstandard  window  (such  as  a non  WC_FRAME  class). 

All  of  the  controls  are  created  with  the  standard  FID_*  window  identifiers;  see  Chapter  15,  Frame 
Control  Window  Processing. 

The  controls  are  created  but  not  formatted.  Formatting  must  be  done  by  setting  the  required 
positions.  All  controls  are  created  with  position  and  size  set  to  zero  and  WS_VISIBLE  is  not  set. 
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Create  Frame  Controls 


Related  Functions 

• WinCalcFrameRect 

• WinCreateStdWindow 

• WinCreateWindow 

• WinDefWindowProc 

• WinDestroyWindow 

• WinQueryClassInfo 

• WinQueryClassName 

• WinRegisterClass 

• WinSubclassWindow 

Example  Code 

This  example  creates  frame  controls  (title  bar,  system  menu,  size  border,  and  min/max  buttons)  for 
a button  window  created  by  WinCreateWindow.  The  new  controls  are  owned  by  and  children  of  the 
button  window. 


fdefine  INCL_WINWINDOWMGR  /*  Window  Manager  Functions 

*/ 

fdefine  INCL_WINLISTBOXES  /*  List  Box  definitions 

*/ 

fdefine  INCL_WINFRAMEMGR  /*  Frame  Manager  Functions 

*/ 

finclude  <os2.h> 

HWND  hwnd; 

/*  cursor  display  window 

*/ 

ULONG  fl Style; 

/*  window  style 

*/ 

USHORT  Buttonld; 

/*  window  id  (app  supplied) 

*/ 

BOOL  fSuccess; 

/*  success  indicator 

*/ 

FRAMECDATA  pFcdata; 

/*  Frame-control  data 

*/ 

USHORT  usFrameld; 

/*  frame  resource  id  (app  supplied) 

*/ 

fl Style  = WS_VISIBLE; 

/*  create  window  visible 

*/ 

/*  create  button  window  (no  frame  controls)  */ 

hwnd  = WinCreateWindow(HWND_DESKTOP,  /*  parent  window 

*/ 

WC_BUTT0N,  /*  class  name 

*/ 

"new  button",  /*  window  text 

*/ 

fl  Style,  /*  window  style 

*/ 

0,  0,  /*  position  (x,y) 

*/ 

200,  100,  /*  size  (width, height) 

*/ 

0L,  /*  owner  window 

*/ 

HWND_T0P,  /*  sibling  window 

*/ 

Buttonld,  /*  window  id 

*/ 

NULL,  /*  control  data 

*/ 

NULL);  /*  presentation  parms 

*/ 

y****************************** 
* initialize  frame  structure  * 
****************************** 


/ 

pFcdata. cb  = si  zeof (FRAMECDATA) ; 

/* 

Length  */ 

/*  Frame-creation  flags  */ 

pFcdata.  flCreateFlags  = FCFJTTLEBAR 

| FCF_SYSMENU  | 

FCF_SIZEBORDER  | FCF  MINMAX; 

pFcdata. hmodResources  = 0L; 

/* 

resource  in  EXE  */ 

pFcdata. idResources  = usFrameld; 

/* 

resource  id  */ 

/*  create  frame  controls;  display  'button  frame'  on  title  bar  */ 
fSuccess  = WinCreateFrameControls(hwnd,  &pFcdata,  "button  frame"); 
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Create  Help  Instance 


#define  INCL_WINHELP  /*  Or  use  INCL_WIN  or  INCL_PM  */ 


HWND  WinCreateHelpInstance  (HAB  hab,  PHELPINIT  phinltHMInltStructure) 


This  function  creates  an  instance  of  the  help  manager  with  which  to  request  help  manager  functions. 


Parameters 

hab  (HAB)  - input 

Anchor-block  handle. 

The  handle  of  the  application  anchor  block  returned  from  the  Winlnitialize  function. 

phinltHMInltStructure  (PHELPINIT)  - input/output 
Help  manager  initialization  structure. 


Returns 

Help  manager  handle. 

NULLHANDLE  Error  occurred 
Other  Help  manager  handle. 

Remarks 

If  an  error  occurs,  it  is  in  the  ulReturnCode  parameter  of  the  HELPINIT  structure. 


Related  Functions 

• WinAssociateHelpinstance 

• WinCreateHelpTable 

• WinDestroyHelpinstance 

• WinLoadHelpTable 

• WinQueryHelpinstance 

Example  Code 

This  example  shows  a typical  main  function  for  an  application  which  uses  help.  Following  creation  of 
the  main  application  window  the  help  manager  is  initialized  and  associated  with  the  window.  The 
help  table  is  defined  in  the  application's  resources.  When  the  window  is  destroyed,  terminating  the 
application,  the  help  instance  is  also  destroyed. 

Idefine  INCL=_WIN 
linclude  <os2.h> 

#define  IDHT_APPLICATION  100  /*  id  of  HELP  TABLE  in  resource  file 

*/ 

main ( int  argc,  char  *argv[],  char  *envp[]  ) 

{ 

HAB  hab  = Winlni ti al i ze(  0 ); 

HMQ  hmq  = WinCreateMsgQueue(  hab,  0 ); 

HWND  hwnd; 

HWND  hwndCl ient; 

HWND  hwndHelp; 

QMSG  qmsg; 

ULONG  fl Style; 

HELPINIT  helpinit; 
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/*  Setup  the  help  initialization  structure  */ 
helpinit.cb  = sizeof(  HELPINIT  ); 
helpinit.ulReturnCode  = 0L; 
helpinit.pszTutorialName  = (PSZ)NULL; 

/*  Help  table  in  application  resource  */ 

help  ini t.phtHelpTable  = (PHELPTABLE)MAKEULONG(  IDHT_APPLICATION,  Oxffff  ); 
helpinit.hmodHelpTableModule  = NULLHANDLE; 

/*  Default  action  bar  and  accelerators  */ 
helpinit.hmodAccelActionBarModule  = NULLHANDLE; 
helpinit.idAccelTable  = 0; 
helpinit.idActionBar  = 0; 
helpinit.pszHelpWindowTitle  = "APPNAME  HELP"; 
hel  pi ni t . f ShowPanel Id  = CMIC_SHOW_PANEL_ID; 
helpinit.pszHelpLibraryName  = "APPNAME.HLP"; 

/*  Register  the  class  */ 
if(  WinRegisterClass(  ...  ) ) 

{ 

/*  create  the  main  window  */ 

fl Style  = FCF_STANDARD; 

hwnd  = WinCreateStdWindow(  ...  ); 

if(  hwnd  ) 

{ 

/*  Create  and  associate  the  help  instance  */ 
hwndHelp  = WinCreateHelpInstance(  hab,  &hel pi ni t ); 

if(  hwndHelp  &&  WinAssociateHelpInstance(  hwndHelp,  hwnd  ) ) 

{ 

/*  Process  messages  */ 

while(  WinGetMsg(  hab,  &qmsg,  NULLHANDLE,  0,  0 ) ) 

{ 

WinDispatchMsg(  hab,  &qmsg  ); 

} /*  endwhile  */ 

} 

/*  Remove  help  instance  - note:  add  */ 

/*  WinAssociateHelpInstance(  NULLHANDLE,  hwnd  );  */ 

/*  to  WM  DESTROY  processing  to  remove  the  association.  */ 
WinDestroyHelpInstance(  hwndHelp  ); 

} 

} 

/*  finish  the  cleanup  and  exit  */ 

WinDestroyMsgQueue(  hmq  ); 

WinTerminate(  hab  ); 
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Create  Help  Table 


#define  INCL_WINHELP  /*  Or  use  INCL_WIN  or  INCL_PM  */ 


BOOL  WinCreateHelpTable  (HWND  hwndHelpInstance,  PHELPTABLE  phtHelpTable) 


This  function  is  used  to  identify  or  change  the  help  table. 


Parameters 

hwndHelpInstance  (HWND)  - input 

Handle  of  an  instance  of  the  help  manager. 

This  is  the  handle  returned  by  the  WinCreateHelpinstance  call. 

phtHelpTable  (PHELPTABLE)  - input 

Help  table  allocated  by  the  application. 


Returns 

Success  indicator: 

TRUE  Successful  completion 
FALSE  Error  occurred. 

Remarks 

This  function  corresponds  to  the  HM_CREATE_HELP_TABLE  message  that  identifies  a help  table  that 
is  in  memory. 


Related  Functions 

• WinAssociateHelpinstance 

• WinCreateHelpinstance 

• WinDestroyHelpinstance 

• WinLoadHelpTable 

• WinQueryHelpinstance 

Related  Messages 

• HM_CREATE_HELP_TABLE 
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Example  Code 

This  example  creates  a help  table  in  memory  and  passes  the  table  to  the  Help  Manager  via 
WinCreateHelpTable.  The  help  instance  must  have  been  created  by  WinCreateHelpInstance. 

fdefine  INCL_WINHELP 
linclude  <os2.h> 


/*  defines  for  window  id's,  menu  items,  controls,  panels,  etc.  should  */ 
/*  be  inserted  here  or  in  additional  include  files.  */ 


/*  Subtable  for  the  main  window's  help  */ 

HELPSUBTABLE  phtMainTable[]  = { 2,  /*  length  of  each 

entry  */ 


/*  fill  in  one  line  for 
IDM_FILE,  PANELID 
IDM_FILENEW,  PANELID 
IDM_FILEOPEN,  PANELID 
IDM_FILESAVE,  PANELID 
IDM_FILESAVEAS,  PANELID 
I DM  FILEEXIT,  PANELID 


each  menu  item 

FILEMENU, 

FILENEW, 

FILEOPEN, 

FILESAVE, 

FILESAVEAS, 

FILEEXIT  }; 


*/ 


/*  Subtable  for  the  dialog  window's  help  */ 

HELPSUBTABLE  phtDlgTable[]  = { 2,  /*  length  of  each 

entry  */ 

/*  fill  in  one  line  for  each  control  */ 
IDC_EDITFLD,  PANELID_DLGEDITFLD, 

IDC_0K,  PANELID_DLGOK, 

IDC_CANCEL,  PAN  E L I D_D  LGC ANC  EL , 

IDC_HELP,  PANELID_HELP  }; 

/*  Help  table  for  the  applications  context  sensitive  help  */ 

HELPTABLE  phtHelpTable[]=  { WINDOWID_MAIN,  phtMainTable, 

PANELID_MAINEXT, 

WINDOWID_DLG,  phtDlgTable,  PANELID_DLGEXT, 
0,  NULL,  0 }; 


BOOL  CreateHel pTable(  HWND  hWnd  ) 

{ 

BOOL  bSuccess  = FALSE; 

HWND  hwndHelp; 

/*  get  the  associated  help  instance  */ 
hwndHelp  = WinQueryHelpInstance(  hWnd  ); 

if(  hwndHelp  ) 

{ 

/*  pass  address  of  help  table  to  the  help  manager  */ 
bSuccess  = WinCreateHelpTable(  hwndHelp,  phtHelpTable  ); 

} 


/*  return  success  indicator  */ 
return  bSuccess; 
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Create  Menu 


#define  INCL_WINMENUS  /*  Or  use  INCL_WIN  or  INCL_PM  */ 


HWND  WinCreateMenu  (HWND  hwndOwner,  PVOID  pmtMenutmp) 


This  function  creates  a menu  window  from  the  menu  template. 


Parameters 

hwndOwner  (HWND)  - input 

Owner-  and  parent-window  handle  of  the  created  menu  window. 

If  this  is  HWND_OBJECT  or  a window  handle  returned  by  the  WinQueryObjectWindow  call,  the 
menu  window  is  created  as  an  object  window. 

HWND_DESKTOP  The  desktop  window 

HWND_OBJECT  Object  window 

Other  Specified  window. 

pmtMenutmp  (PVOID)  - input 

Menu  template  in  binary  format. 


Returns 

Menu-window  handle. 

Possible  returns  from  WinGetLastError 

PMERRJNVALID  HWND  An  invalid  window  handle  was  specified. 

Remarks 

The  menu  window  is  created  with  an  identity  of  FID_MENU. 

When  a WC_MENU  window  is  created  with  the  WinCreateWindow  call,  pCtIData  is  assumed  to  be  a 
menu  template,  which  is  used  to  create  the  menu.  If  pCtIData  is  NULL,  an  empty  menu  is  created. 


Related  Functions 

• WinLoadMenu 

• WinPopupMenu 
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Example  Code 

This  code  will  load  a menu  template  from  a dll  and  then  use  it  to  add  a menu  to  the  frame  window 
hwndFrame  which  has  been  previously  created  without  a menu. 

HMOD  hmod; 

HWND  hwndFrame,  hwndMenu; 

USHORT  idMenu  = 999; 

BYTE  FAR  *lpmt; 

DosLoadModul e (NULL,  0,  "MYDLL.DLL" , &hmod); 

/*  Load  menu  template  */ 

DosGetResource2(hmod,  (USHORT)RT_MENU,  idMenu,  &1 pmt) ; 
hwndMenu  = WinCreateMenu (hwndFrame,  lpmt);  /*  Create  a menu  */ 

DosFreeResource(lpmt) ; /*  free  menu  template  resource  */ 
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Create  Message  Queue 


#define  INCL_WINMESSAGEMGR  /*  Or  use  INCL_WIN  or  INCL_PM.  Also  in  COMMON  section  */ 


HMQ  WinCreateMsgQueue  (HAB  hab,  LONG  IQueuesIze) 


This  function  creates  a message  queue. 

Parameters 

hab  (HAB)  - input 

Anchor-block  handle. 

IQueuesIze  (LONG)  - input 
Maximum  queue  size. 

This  is  the  maximum  number  of  messages  that  can  be  queued. 
0 Use  the  system  default  queue  size. 

Other  Maximum  queue  size. 


Returns 

Message-queue  handle: 

NULLHANDLE  Queue  cannot  be  created. 
Other  Message-queue  handle. 


Possible  returns  from  WinGetLastError 

PMERRHEAPMAXSIZEREACHED 

P M E R R_HE  AP_OUT_OF_M  EMORY 
PMERRRESOURCENOTFOUND 
PMERR_NOT_IN_A_PM_SESSION 

PMERRQUEUEALREADYEXISTS 


The  heap  has  reached  its  maximum  size  (64KB),  and 
cannot  be  increased. 

An  attempt  to  increase  the  size  of  the  heap  failed. 

The  specified  resource  identity  could  not  be  found. 

An  attempt  was  made  to  access  function  that  is  only 
available  from  PM  programs  from  a non-PM  session. 

An  attempt  to  create  a message  queue  for  a thread  failed 
because  one  already  exists  for  the  calling  thread. 


Remarks 

Most  PM  calls  require  a message  queue.  WinCreateMsgQueue  must  be  issued  after  the  Winlnitialize 
function,  but  before  any  other  PM  calls  are  invoked.  It  must  be  issued  only  once  per  thread. 

The  system  default  queue  size  allows  for  10  messages. 
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Create  Message  Queue 


Related  Functions 

• WinCancelShutdown 

• Winlnitialize 

• WinTerminate 

• WinBroadcastMsg 

• WinDestroyMsgQueue 

• WinDispatchMsg 

• WinGetDIgMsg 

• WinGetMsg 

• WinlnSendMsg 

• WinPeekMsg 

• WinPostMsg 

• WinPostQueueMsg 

• WinQueryMsgPos 

• WinQueryMsgTime 

• WinQueryQueuelnfo 

• WinQueryQueueStatus 

• WinRegisterllserDatatype 

• WinRegisterllserMsg 

• WinSendDIgltemMsg 

• WinSendMsg 

• WinSetClassMsglnterest 

• WinSetMsglnterest 

• WinSetMsgMode 

• WinSetSynchroMode 

• WinWaitMsg 

Example  Code 

This  example  creates  a message  queue  of  default  size. 


fdefine  INCL_WINMESSAGEMGR  /*  Window  Message  Functions  */ 
fdefine  INCL_WINWINDOWMGR  /*  Window  Manager  Functions  */ 
finclude  <os2.h> 


HAB 

hab; 

/*  anchor-block  handle 

*/ 

HMQ 

hmq; 

/*  message  queue  handle 

*/ 

QMSG 

qmsg; 

/*  message 

*/ 

hab  = Winlnitial i ze (0) ; /*  initialize  PM  */ 

hmq  = WinCreateMsgQueue (hab,  0);  /*  create  default  size  queue  */ 

/* 

. initialize  windows 


*/ 

/*  get  and  dispatch  messages  from  queue  */ 
while  (WinGetMsg(hab,  &qmsg,  0,  0,  0)) 
WinDispatchMsg(hab,  &qmsg); 
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Create  Workplace  Object 


#define  INCL_WINWORKPLACE 


HOBJECT  WinCreateObject  (PSZ  pszClassName,  PSZ  pszTitle,  PSZ  pszSetupStrlng, 

PSZ  pszLocation,  ULONG  ulFlags) 


This  WinCreateObject  function  creates  an  instance  of  object  class  pszClassName,  with  title  pszTitle, 
and  places  the  icon  and  title  in  the  location  referred  to  by  pszLocation. 


Parameters 

pszClassName  (PSZ)  - input 

A pointer  to  a zero-terminated  string  which  contains  the  name  of  the  class  of  which  this  object  is 
a member. 

pszTitle  (PSZ)  - input 

A pointer  to  a zero-terminated  string  which  contains  the  initial  title  of  the  object  as  it  is  to  appear 
when  displayed  on  the  user  interface  underneath  an  icon  or  on  the  title  bar  of  an  open  object. 

pszSetupStrlng  (PSZ)  - input 

Pointer  to  setup  string. 

pszLocation  (PSZ)  - input 
Folder  location. 


This  value  can  be  in  any  of  the  following  formats: 


• Predefined  object  ids  of  system  folders. 


“<WP_NOWHERE>” 
“ <WP_DESKTOP>” 
“ < W P_OS2S  YS>” 
“<WP_TEMPS>” 
“<WP_CONFIG>” 
“<WP_START>” 
“<WP_INFO>” 
“<WP_DRIVES>” 


The  hidden  folder. 

The  Desktop. 

The  System  folder. 

The  Templates  folder. 
The  System  Setup  folder. 
The  Startup  folder. 

The  Information  folder. 
The  Drives  folder. 


• Real  name  specified  as  a fully  qualified  path  name. 


ulFlags  (ULONG)  - input 
Creation  flags: 

• CO_FAILIFEXISTS 

• CO_REPLACEIFEXISTS 


Returns 

Success  indicator: 


NULLHANDLE  Error  occurred. 

Other  A handle  to  the  object  created.  This  handle  is  persistent  and  can  be  used  for 

the  WinSetObjectData  and  WinDestroyObject  function  calls. 
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Remarks 

The  pszSetupString  contains  a series  of  "keyname=value"  pairs  separated  by  commas,  that  change 
the  behavior  of  the  object.  Each  object  class  documents  its  keynames  and  the  parameters 
parameters  it  expects  to  see  immediately  following.  Note  that  ALL  parameters  have  safe  defaults,  so 
it  is  never  necessary  to  pass  unnecessary  parameters  to  an  object. 

These  are  the  keyname- value  pairs  supported  by  the  WPObject  class: 


KEYNAME 

VALUE 

Description 

TITLE 

Title 

This  sets  the  object's  title.  This  is  equivalent  to 
calling  the  wpSetTitle  method. 

ICON 

filename 

This  sets  the  object's  icon.  This  is  equivalent  to 
calling  the  wpSetlconData  method. 

HELPPANEL 

id 

This  sets  the  object's  default  help  panel.  This  is 
equivalent  to  calling  the  wpSetDefaultHelp 
method. 

TEMPLATE 

YES 

This  sets  the  object's  template  property.  This  is 
equivalent  to  calling  the  wpSetStyle  method  with 
a style  of  OBJSTYLE_TEMPLATE. 

NO 

This  resets  the  object's  template  property. 

NODELETE 

YES 

This  sets  the  object's  no  delete  property.  This  is 
equivalent  to  calling  the  wpSetStyle  method  with 
a style  of  OBJSTYLE_NODELETE. 

NO 

This  resets  the  object's  no  delete  property. 

NOCOPY 

YES 

This  sets  the  object's  no  copy  property.  This  is 
equivalent  to  calling  the  wpSetStyle  method  with 
a style  of  OBJSTYLE_NOCOPY. 

NO 

This  resets  the  object's  no  copy  style. 

NOMOVE 

YES 

This  sets  the  object's  no  move  property.  This  is 
equivalent  to  calling  the  wpSetStyle  method  with 
a style  of  OBJSTYLE_NOMOVE. 

NO 

This  resets  the  object's  no  move  property. 

NOLINK 

YES 

This  sets  the  object's  no  link  property.  This  is 
equivalent  to  calling  the  wpSetStyle  method  with 
a style  of  OBJSTYLE_NOLINK. 

NO 

This  resets  the  object's  no  link  property. 

Related  Functions 

• WinRegisterObjectClass 

• WinDeregisterObjectClass 

• WinDestroyObject 

• WinReplaceObjectClass 

• WinSetObjectData 
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Create  Pointer 


#define  INCL_WINPOINTERS  /*  Or  use  INCL_WIN  or  INCL_PM  */ 


HPOINTER  WinCreatePointer  (HWND  hwndOeskTop,  H BITMAP  hbmBitMap,  BOOL  fPointerSize, 

LONG  IxHotspot,  LONG  lyHotspot) 


This  function  creates  a pointer  from  a bit  map. 


Parameters 

hwndDeskTop(HWND)  - input 

Desktop-window  handle  or  HWND_DESKTOP. 

hbmBitMap  (HBITMAP)  - input 

Bit-map  handle  from  which  the  pointer  image  is  created. 

The  bit  map  must  be  logically  divided  into  two  sections  vertically,  each  half  representing  one  of 
the  two  images  used  as  the  successive  drawing  masks  for  the  pointer. 

fPointerSize  (BOOL)  - input 
Pointer-size  indicator: 

TRUE  The  bit  map  should  be  stretched  (if  necessary)  to  the  system  pointer  dimensions. 

FALSE  The  bit  map  should  be  stretched  (if  necessary)  to  the  system  icon  dimensions. 

IxHotspot  (LONG)  - input 

x-offset  of  hot  spot  within  pointer  from  its  lower  left  corner  (in  pels). 
lyHotspot  (LONG)  - input 

y-offset  of  hot  spot  within  pointer  from  its  lower  left  corner  (in  pels). 


Returns 

Pointer  handle: 

NULLHANDLE  Error 

Other  Handle  of  the  newly  created  pointer. 

Possible  returns  from  WinGetLastError 

PMERR  INVALID  HWND  An  invalid  window  handle  was  specified. 

PMERR_HBITMAP_BUSY  An  internal  bit  map  busy  error  was  detected.  The  bit  map 

was  locked  by  one  thread  during  an  attempt  to  access  it 
from  another  thread. 

Remarks 

A pointer  can  be  created  either  as  a true  pointer  (at  pointer  size),  or  as  an  icon  pointer  (at  icon  size). 
The  latter  is  useful  when  using  icons  as  direct-manipulation  objects  that  the  user  can  “pick  up”  and 
move  about  the  screen  as  a means  of  performing  some  operation. 

See  also  WinCreatePointerlndirect. 

This  function  makes  copies  of  the  supplied  bit  maps. 
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Create  Pointer 


Related  Functions 

• WinCreatePointerlndirect 

• WinDestroyPointer 

• WinDrawPointer 

• WinLoadPointer 

• WinQueryPointer 

• WinQueryPointerlnfo 

• WinQueryPointerPos 

• WinQuerySysPointer 

• WinSetPointer 

• WinSetPointerPos 

• WinShowPointer 

Example  Code 

This  example  creates  a pointer  from  a bit  map  during  the  creation  of  the  window  (WM_CREATE). 
The  bit  map  (id  IDP_BITMAP  in  the  EXE  file)  is  loaded  via  GpiLoadBitmap. 


Idefine  INCL_WINPOINTERS  /*  Window  Pointer  Functions  */ 
Idefine  INCL_GPIBITMAPS  /*  Graphics  bit  map  Functions  */ 
linclude  <os2.h> 

HPS  hps;  /*  presentation-space  handle  */ 
HWND  hwnd;  /*  window  handle  */ 
HPOINTER  hptr;  /*  bit-map  pointer  handle  */ 
HBITMAP  hbm;  /*  bit-map  handle  */ 


case  WM_CREATE: 

hps  = WinBeginPaint(hwnd,  NULLHANDLE,  NULL); 
hbm  = GpiLoadBitmap (hps,  0L,  IDP_BITMAP,  64L,  64L); 
WinEndPaint(hps) ; 

hptr  = WinCreatePointer(HWND_DESKTOP,  hbm, 

TRUE,  /*  use  true  (system)  pointer  */ 
0,  0);  /*  hot  spot  offset  (0,0)  */ 
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Create  Pointer  Indirect 


#define  INCL_WINPOINTERS  /*  Or  use  INCL_WIN  or  INCL_PM  */ 


H POINTER  WinCreatePointerlndirect  (HWND  hwndDeskTop,  PPOINTERINFO  pptrlPoInterlnfo) 


This  function  creates  a colored  pointer  or  icon  from  a bit  map. 


Parameters 

hwndDeskTop  (HWND)  - input 

Desktop-window  handle  or  HWND_DESKTOP. 

pptrlPoInterlnfo  (POINTERINFO)  - input 
Pointer  information  structure. 

The  fields  in  this  structure  must  be  set  before  the  call  is  made: 

• ulPointer  is  set  to  TRUE  if  a pointer  is  being  created,  or  to  FALSE  if  an  icon  is  being  created 

• xHotspot  and  yHotspot  are  set  to  the  relative  position  in  the  icon  or  pointer  that  is 
associated  with  the  mouse  position 

• hbmPointer  is  a bit  map  that  specifies  the  AND  and  XOR  masks,  as  used  for  black  and  white 
pointers  and  icons 

• hbmColor  is  a color  bit  map  that  describes  the  color  content  of  the  pointer  or  icon. 

It  is  an  error  if  hbmPointer  is  NULLHANDLE.  Also,  the  width  of  hbmPointer  must  be  the  same  as 
that  of  hbmColor,  and  the  height  of  hbmPointer  must  be  double  that  of  hbmColor  (to  allow  for 
both  the  AND  and  the  XOR  mask). 


Returns 

Pointer  handle: 

NULLHANDLE  Error 

Other  Handle  of  the  newly  created  pointer  or  icon. 

Possible  returns  from  WinGetLastError 

PMERRJNVALID  HWND  An  invalid  window  handle  was  specified. 

PMERR_HBITMAP_BUSY  An  internal  bitmap  busy  error  was  detected.  The  bit  map 

was  locked  by  one  thread  during  an  attempt  to  access  it 
from  another  thread. 


Remarks 

A pointer  can  be  created  either  as  a true  pointer  (at  pointer  size),  or  as  an  icon  pointer  (at  icon  size). 
The  latter  is  useful  when  using  icons  as  direct-manipulation  objects  that  the  user  can  “pick  up”  and 
move  about  the  screen  as  a means  of  performing  some  operation  (see  also  WinCreatePointer). 

This  function  makes  copies  of  the  supplied  bit  maps. 
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Create  Pointer  Indirect 


Related  Functions 

• WinCreatePointer 

• WinDestroyPointer 

• WinDrawPointer 

• WinLoadPointer 

• WinQueryPointer 

• WinQueryPointerlnfo 

• WinQueryPointerPos 

• WinQuerySysPointer 

• WinSetPointer 

• WinSetPointerPos 

• WinShowPointer 

Example  Code 

This  example  creates  a colored  pointer  from  a bit  map  during  the  creation  of  the  window 
(WM_CREATE).  The  pointer  bit  map  (id  IDP_BITMAPPTR  in  the  EXE)  and  color  bit  map  (id 
IDPJ3ITMAPCLR  in  the  EXE  file)  are  loaded  via  GpiLoadBitmap. 


fdefine  INCL_WINPOINTERS  /*  Window  Pointer  Functions  */ 
fdefine  INCL_GPIBITMAPS  /*  Graphics  bit  map  Functions  */ 
finclude  <os2.h> 

HPS  bps;  /*  presentation-space  handle  */ 
HWND  hwnd;  /*  window  handle  */ 
HPOINTER  hptr;  /*  bit-map  pointer  handle  */ 
HBITMAP  hbmPointer;  /*  bit-map  handle  (AND/XOR)  */ 
HBITMAP  hbmColor;  /*  bit-map  handle  (color)  */ 
POINTERINFO  pptriPointerlnfo;  /*  pointer  info  structure  */ 


case  WM_CREATE: 

hps  = Wi nBegi nPai nt ( hwnd , NULLHANDLE,  NULL); 

/*  load  pointer  bit  map  */ 

hbmPointer  = GpiLoadBitmap  (hps,  NULLHANDLE,  IDPJITMAPPTR,  64L,  128L); 
/*  load  color  bit  map  */ 

hbmColor  = GpiLoadBitmap(hps,  NULLHANDLE,  IDPJITMAPCLR,  64L,  64L); 
WinEndPaint(hps) ; 

/*  initialize  POINTERINFO  structure  */ 
pptriPointerlnfo. fPointer  = TRUE;  /*  creating  pointer  */ 
pptriPointerlnfo.xHotspot  = 0;  /*  x coordinate  of  hotspot  */ 
pptriPointerlnfo.yHotspot  =0;  /*  y coordinate  of  hotspot  */ 
pptriPointerlnfo. hbmPointer  = hbmPointer; 
pptriPointerlnfo. hbmColor  = hbmColor; 

hptr  = WinCreatePointerIndirect(HWND_DESKTOP, 

&pptriPointerInfo) ; 
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#define  INCL_WINFRAMEMGR  /*  Or  use  INCL_WIN  or  INCL_PM.  Also  in  COMMON  section  */ 


HWND  WinCreateStdWindow  (HWND  hwndParent,  ULONG  fIStyle,  PULONG  pfICreateFlags, 

PSZ  pszClassCllent,  PSZ  pszTitle,  ULONG  fIStyleCllent, 
HMODULE  Resource,  ULONG  ulld,  PHWNO  phwndCllent) 


This  function  creates  a standard  window. 

Parameters 

hwndParent  (HWND)  - input 
Parent-window  handle. 

If  this  parameter  is  a window  handle  returned  from  the  WinQueryDesktopWindow  function,  or  is 
HWND_DESKTOP,  a main  window  is  created. 

If  hwndParent  is  a window  handle  returned  from  WinQueryObjectWindow,  or  is  HWND_OBJECT, 
an  object  window  is  created. 

fIStyle  (ULONG)  - input 
Frame-window  style. 

This  is  a combination  of  any  of  the  WS_*  styles  (see  “Window  Styles”  on  page  12-2)  and  the 
FS_*  (see  “Frame  Control  Styles”  on  page  15-3)  frame  styles. 

The  interpretation  of  the  parameters  is  affected  by  the  use  of  all  the  styles,  except  for 
WS_MINIMIZED  and  WS_MAXIMIZED.  These  two  styles  are  ignored  if  they  are  specified. 

pfICreateFlags  (PULONG)  - input 
Frame-creation  flags. 

This  contains  a combination  of  any  of  the  FCF_*  flags. 

The  interpretation  of  the  parameters  is  affected  by  the  use  of  these  flags;  see  /FCFVALS/. 

pszClassCllent  (PSZ)  - input 
Client-window  class  name. 

If  pszClassClient  is  not  a zero-length  string,  a client  window  of  style  fIStyleClient  and  class 
pszClassClient  is  created.  pszClassClient  is  either  an  application  specified  name  as  defined  by 
WinRegisterClass  or  the  name  of  a preregistered  WC_*  class;  see  “Control  Window  Message 
Processing”  on  page  11-2.  Preregistered  class  names  are  of  the  form  ‘#nnnnn’,  where  nnnnn  is 
1 through  5 digits  corresponding  to  the  value  of  the  WC_*  class  name  constant. 

If  pszClassClient  is  NULL,  no  client  area  is  created. 

This  parameter  can  also  be  specified  directly  as  a WC_*  constant. 

pszTitle  (PSZ)  - input 
Title-bar  text. 

This  is  ignored  if  FCF_TITLEBAR  (or  FCF_STANDARD)  is  not  specified  in  pfICreateFlags. 

fIStyleCllent  (ULONG)  - input 
Client-window  style. 

This  is  ignored  if  pszClassClient  is  a zero-length  string. 
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Resource  (HMODULE)  - input 
Resource  identifier. 

This  is  ignored  unless  FCF_MENU,  FCF_STANDARD,  FCF_ACCELTABLE,  or  FCFJCON  is 
specified. 

NULLHANDLE  Resource  definitions  are  contained  in  the  application  .EXE  file. 

Other  The  module  handle  returned  by  the  DosLoadModule  or  DosGetModHandle  call  of  the 
Dynamic  Link  Library  (DLL)  containing  the  resource  definitions. 

ulld  (ULONG)  - input 

Frame-window  identifier. 

The  identifier  within  the  resource  definition  of  the  required  resource. 

It  is  the  responsibility  of  the  application  to  ensure  that  all  of  the  resources  related  to  one  frame 
window  have  the  same  ulld  value. 

phwndCllent  (PHWND)  - output 
Client-window  handle. 

This  is  returned  if  a client  window  is  created. 


Returns 

Frame-window  handle. 

This  is  NULLHANDLE  if  no  window  is  created. 


Possible  returns  from  WinGetLastError 

PMERRJNVALIDHWND 
PM  ERR_INVALID_FLAG 

PM  ERR _IN  VALID _INTEGER_ATOM 
PMERRJNVALIDATOMNAME 
PMERR  ATOM  NAME  NOT  FOUND 


An  invalid  window  handle  was  specified. 

An  invalid  bit  was  set  for  a parameter.  Use  constants 
defined  by  PM  for  options,  and  do  not  set  any  reserved 
bits. 

The  specified  atom  is  not  a valid  integer  atom. 

An  invalid  atom  name  string  was  passed. 

The  specified  atom  name  is  not  in  the  atom  table. 
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Remarks 

The  window  is  created  with  zero  width  and  depth  and  positioned  at  the  bottom  left  of  the  hwndParent, 
unless  FCF_SHELLPOSITION  is  specified,  in  which  case  the  size  and  position  are  set  by  the  shell. 

The  window  can  be  positioned  and  sized  by  use  of  WinSetWindowPos. 

If  WS_VISIBLE  is  set,  the  frame  window  is  created  visible.  It  is  recommended  that  standard  windows 
that  are  not  main  windows  are  created  with  WS_VISIBLE  not  set. 

hwndFrame  is  the  window  handle  of  the  frame  window,  that  is,  the  window  of  class  WC_FRAME,  and 
has  a parent  of  hwndParent. 

The  frame  window  is  created  with  identity  ulld,  all  the  component  windows,  known  as  the  frame 
controls,  have  the  standard  window  identifiers  FID_*;  see  Chapter  15,  “Frame  Control  Window 
Processing”  on  page  15-1.  The  identifier  FID_CLIENT  is  used  for  the  client  area  of  the  window. 

It  may  be  necessary  to  change  the  ulld  of  the  frame  window  after  it  has  been  created,  so  that  another 
frame  window  can  be  created  with  the  same  resource  tables,  and  still  maintain  distinct  window 
identities.  This  can  be  achieved  with  the  WinSetWindowUShort  call. 

Some  combinations  of  frame  control  flags  are  valid,  but  leave  visual  holes  in  the  frame  window. 
Specifically,  if  the  pfICreateFlags  parameter  specifies  any  of  FCF_SYSMENU,  FCF_MINBUTTON, 
FCF_MAXBUTTON  or  FCF_MINMAX,  but  not  FCF_TITLEBAR,  the  area  of  the  top  title  line  between  the 
optional  system  menu  and  the  minimize/maximize  icons  is  not  drawn  by  the  default  frame  window 
procedure. 

None  of  the  following  can  be  used  with  WinCreateStdWindow: 

• WS_CLIPCHILDREN  for  the  frame  style 

• WS_CLIPSIBLINGS  for  the  style  of  the  client  window  or  any  of  the  frame  control  windows 

• CS_CLIPSIBLINGS  for  the  class  style  of  the  window. 

If  any  of  the  above  are  specified,  the  window  is  not  redrawn  correctly.  Any  style  can  be  used  for  the 
children  of  the  client.  If  it  really  is  required  that  a client  or  a frame  control  is  CLIPSIBLINGS,  the 
application  must  ensure  that  it  is  in  front  of  the  client  and  all  the  other  frame  controls,  for  it  to  be 
drawn. 

Related  Functions 

• WinCalcFrameRect 

• WinCreateFrameControls 

• WinCreateWindow 

• WinDefWindowProc 

• WinDestroyWindow 

• WinQueryClassinfo 

• WinQueryClassName 

• WinRegisterClass 

• WinSubclassWindow 
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Example  Code 

This  example  shows  a typical  initialization  function  for  a window.  The  function  first  registers  the 
window  class,  then  calls  WinCreateStdWindow  to  create  a standard  window  and  returns  immediately 
if  the  function  fails.  Otherwise,  it  continues  on  to  do  other  initialization  processing.  Note:  The 
FCF_STANDARD  constant  can  only  be  used  if  you  have  all  the  resources  in  defines.  If  you  use  this 
constant  without  an  accelerator  table  for  example,  the  function  will  fail. 


Idefine  INCL_WINFRAMEMGR  /*  Window  Frame  Functions  */ 

linclude  <os2.h> 

Idefine  IDM_RESOURCE  1 

HAB  hab;  /*  Anchor-block  handle  */ 

CHAR  szClassName[]  = "Generic";  /*  window  class  name  */ 

HWND  hwndClient;  /*  handle  to  the  client  */ 

HWND  hwndFrame;  /*  handle  to  the  frame  */ 

PFNWP  GenericWndProc; 

BOOL  GenericInitO 

{ 

ULONG  fl Style; 


fl  Style  = FCF_STANDARD; 

if  (!WinRegisterClass(hab,  szClassName,  GenericWndProc,  OL,  0)) 
return  (FALSE); 


hwndFrame  = WinCreateStdWindow(HWND_DESKTOP, 

OL,  /*  frame-window  style  */ 
&fl Style,  /*  window  style  */ 
szClassName,  /*  class  name  */ 
"Generic  Application",  /*  window  title  */ 
OL,  /*  default  client  style  */ 
NULLHANDLE,  /*  resource  in  executable  file  */ 
IDM_RESOURCE,  /*  resource  id  */ 


ShwndClient) ; /*  receives  client  window  handle  */ 

if  (! hwndFrame) 
return  (FALSE); 
else  { 

. /*  other  initialization  code  */ 
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#define  INCL_WINSWITCHLIST  /*  Or  use  INCL_WIN  or  INCL_PM  */ 


HS WITCH  WinCreateSwitchEntry  (HAB  hab,  PSWCNTRL  pswctlSwItchData) 


This  function  adds  an  entry  to  the  Window  List. 


Parameters 

hab  (HAB)  - input 

Anchor-block  handle. 

pswctlSwItchData  (PSWCNTRL)  - input 
Switch  data. 

Contains  information  about  the  newly  created  Window  List  entry. 

If  the  szSwtitle[MAXNAMEL  + 7]  field  of  the  SWCNTRL  structure  is  NULL,  the  system  uses  the 
name  under  which  the  application  is  started.  This  only  applies  for  OS/2  Version  2.0  programs, 
and  only  for  the  first  call  to  this  function  since  the  program  started.  Otherwise,  a NULL  entry 
name  is  invalid. 

Leading  and  trailing  blanks  are  removed  from  the  title,  which,  if  necessary,  is  also  truncated  to 
60  characters. 

If  the  hprog  field  of  the  SWCNTRL  structure  is  NULLHANDLE,  the  value  used  by  the  system  when 
the  program  was  loaded  (if  it  has  been  loaded)  is  substituted. 

If  the  idProcess  field  of  the  SWCNTRL  structure  is  0,  the  current  process  ID  is  used. 

If  the  idSession  field  of  the  SWCNTRL  structure  is  0,  the  current  session  ID  is  used. 


Returns 

Handle  to  the  newly  created  Window  List  entry. 

There  is  a system  limit  to  the  number  of  Window  List  entries.  However,  this  is  a large  number 
(several  hundred)  and  is  unlikely  to  be  reached  in  practice  since  other  system  limits,  such  as 
memory  size,  are  likely  to  be  reached  first. 

NULLHANDLE  Error  occurred 

Other  Handle  to  the  newly  created  Window  List  entry. 


Possible  returns  from  WinGetLastError 


PMERRNOSPACE 

PMERRINVALIDWINDOW 

PMERRINVALIDSESSIONID 


The  limit  on  the  number  of  Window  List  entries  has  been 
reached  with  WinAddSwitchEntry. 

The  window  specified  with  a Window  List  function  is  not  a 
valid  frame  window. 

The  specified  session  identifier  is  invalid.  Either  zero  (for 
the  application’s  own  session)  or  a valid  identifier  must 
be  specified. 


Remarks 

Both  this  function  and  the  WinRemoveSwitchEntry  function  are  not  required  if  the  main  window  is 
created  with  the  frame  creation  flags  FCF  TASKLIST  or  FCF  STANDARD,  as  these  styles 
automatically  update  the  Window  List  when  the  main  window  is  created  or  destroyed,  or  when  its 
title  changes  (see  also  WinAddSwitchEntry). 
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Related  Functions 

• WinAddSwitchEntry 

• WinChangeSwitchEntry 

• WinQuerySessionTitle 

• WinQuerySwitchEntry 

• WinQuerySwitchHandle 

• WinQuerySwitchList 

• WinQueryTaskSizePos 

• WinQueryTaskTitle 

• WinRemoveSwitchEntry 

• WinSwitchToProgram 

Example  Code 

This  example  creates  a task-list  entry  for  program  name  'Generic:  NEW.APP'. 
fdefine  INCL_WINSWITCHLIST  /*  Window  Switch  List  Functions  */ 


fdefine  INCL_WINWINDOWMGR  /*  Window  Manager  Functions  */ 
finclude  <os2.h> 

HSWITCH  hswitch;  /*  task-list  entry  handle  */ 
SWCNTRL  swctl ; /*  switch-control  data  */ 
PID  pid;  /*  process  id  */ 
HAB  hab;  /*  anchor-block  handle  */ 
HWND  hwndFrame;  /*  frame  handle  */ 


hab  = Wi nQueryAnchorBlock (hwndFrame) ; /*  gets  anchor  block  */ 

WinQueryWindowProcess(hwndFrame,  &pid,  NULL);/*  gets  process  id  */ 

/*  initialize  switch  structure  */ 


swctl. hwnd  = hwndFrame;  /*  window  handle  */ 
swctl .hwndlcon  = NULLHANDLE;  /*  icon  handle  */ 
swctl. hprog  = NULLHANDLE;  /*  program  handle  */ 
swctl .idProcess  = pid;  /*  process  identifier  */ 
swctl .idSession  = 0;  /*  session  identifier  */ 
swctl .uchVisibility  = SWL_VISIBLE;  /*  visibility  */ 
swctl. fbJump  = SWL_JUMPABLE;  /*  jump  indicator  */ 
strcpy(swctl .szSwtitle, "Generic:  NEW.APP");  /*  program  name  */ 


hswitch  = WinCreateSwitchEntry(hab,  &swctl); 
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#define  INCL_WINWINDOWMGR  /*  Or  use  INCL_WIN  or  INCL_PM  7 


HWND  WlnCreateWindow  (HWND  hwndParent,  PSZ  pszClassName,  PSZ  pszName, 

ULONG  fIStyle,  LONG  Ixcoord,  LONG  lycoord,  LONG  IWidth, 

LONG  IHelght,  HWND  hwndOwner,  HWND  hwndBehlnd,  ULONG  Id, 
PVOID  pCtIData,  PVOID  pPresParams) 


This  function  creates  a new  window  of  class  pszClassName  and  returns  hwnd. 


Parameters 

hwndParent  (HWND)  - input 
Parent-window  handle. 

If  hwndParent  is  a desktop  window  handle,  or  is  HWND_DESKTOP,  a main  window  is  created. 

If  hwndParent  is  HWND_OBJECT,  or  is  a window  handle  returned  by  WinQueryObjectWindow,  an 
object  window  is  created. 

pszClassName  (PSZ)  - input 
Registered-class  name. 

pszClassName  is  either  an  application-specified  name  as  defined  by  WinRegisterClass  or  the 
name  of  a preregistered  WC_*  class;  see  Control  Window  Message  Processing.  Preregistered 
class  names  are  of  the  form  ‘#nnnnn’,  where  nnnnn  is  1 through  5 digits  corresponding  to  the 
value  of  the  WC_*  class-name  constant. 

This  parameter  can  also  be  specified  directly  as  a WC_*  constant. 

pszName  (PSZ)  - input 
Window  text. 

The  actual  structure  of  the  data  is  class-specific.  It  is  usually  a null-terminated  string  that  is 
often  displayed  in  the  window. 

fIStyle  (ULONG)  - input 
Window  style. 

Ixcoord  (LONG)  - input 

x-coordinate  of  window  position. 

The  value  is  in  window  coordinates  relative  to  the  origin  of  the  parent  window. 

lycoord  (LONG)  - input 

y-coordinate  of  window  position. 

The  value  is  in  window  coordinates  relative  to  the  origin  of  the  parent  window. 

IWidth  (LONG)  - input 

Width  of  window,  in  window  coordinates. 

IHelght  (LONG)  - input 

Height  of  window,  in  window  coordinates. 

hwndOwner  (HWND)  - input 
Owner-window  handle. 

Windows  that  send  messages  send  them  to  their  owner,  as  defined  by  this  parameter.  When  an 
owner  window  is  destroyed,  all  windows  owned  by  it  are  also  destroyed.  The  owner  window 
must  belong  to  the  current  thread. 

hwndBehlnd  (HWND)  - input 
Sibling-window  handle. 

This  is  the  sibling  window  behind  which  hwnd  is  placed.  If  this  parameter  is  HWND_TOP  or 
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HWND_BOTTOM,  hwnd  is  placed  on  top  of  all,  or  behind  all  of  its  siblings.  This  parameter  must 
be  HWND_TOP,  HWND_BOTTOM,  or  a child  of  hwndParent. 

Id  (ULONG)  - input 
Window  identifier. 

A value  given  by  the  application,  that  enables  specific  children  of  a window  to  be  identified.  For 
example,  the  controls  of  a dialog  have  unique  identifiers  so  that  an  owner  can  distinguish  which 
control  has  notified  it.  Window  identifiers  are  also  used  for  frame  windows. 

pCtIData  (PVOID)  - input 
Control  data. 

This  is  class-specific  data  passed  to  the  window  procedure  by  the  WM_CREATE  message. 

pPresParams  (PVOID)  - input 
Presentation  parameters. 

This  is  class-specific  presentation  data  passed  to  the  window  procedure  by  the  WMCREATE 
message. 

Returns 

Window  handle: 

NULLHANDLE  Error  occurred 
Other  Window  handle. 

Possible  returns  from  WinGetLastError 

PMERRJNVALIDHWND 
PMERRINVALIDFLAG 

PMERRINVALIDINTEGERATOM 
PMERRINVALIDATOMNAME 
PMERRATOMNAMENOTFOUND 

Remarks 

The  appearance  and  behavior  of  a window  are  determined  by  its  style,  which  is  the  combination  of 
the  style  established  by  pszClassName  and  fIStyle  ORed  together.  Any  of  the  standard  styles  WS_* 
(see  “Window  Styles”  on  page  12-2)  can  be  used  in  addition  to  any  class-specific  styles  that  may  be 
defined. 

A window  is  usually  created  enabled  and  invisible.  For  more  information  on  the  initial  state  of  a 
created  window,  see  the  list  of  the  standard  window  styles. 

Messages  may  be  received  from  other  processes  or  threads  when  this  function  is  called. 

This  function  sends  the  WM_CREATE  message  to  the  window  procedure  of  the  window  being  created. 

This  function  sends  the  WM_ADJUSTWINDOWPOS  message  after  the  WM_CREATE  message,  and 
before  the  window  is  displayed  (if  applicable).  The  values  passed  are  those  given  to  the 
WinCreateWindow  function.  If  the  window  has  style  WS_VISIBLE,  the  window  is  created  visible. 

The  WM_SIZE  message  is  not  sent  by  the  WinCreateWindow  function  while  the  window  is  being 
created.  Any  required  size  processing  can  be  performed  during  the  processing  of  the  WM  CREATE 
message. 


An  invalid  window  handle  was  specified. 

An  invalid  bit  was  set  for  a parameter.  Use  constants 
defined  by  PM  for  options,  and  do  not  set  any  reserved 
bits. 

The  specified  atom  is  not  a valid  integer  atom. 

An  invalid  atom  name  string  was  passed. 

The  specified  atom  name  is  not  in  the  atom  table. 
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Because  windows  are  often  created  with  zero  height  or  width  and  sized  later,  it  is  good  practice  not 
to  perform  any  size-related  processing  if  the  size  of  the  window  is  zero. 

If  the  WinCreateWindow  function  is  called  for  a window  of  class  WC_FRAME,  the  controls  specified  by 
fICreateFlags  are  created  but  not  formatted.  The  frame  is  formatted  when  a WM_FORMATFRAME 
message  is  received  but  this  is  not  sent  during  window  creation.  To  cause  the  frame  to  format, 
either  a WMFORMATFRAME  message  must  be  sent,  or  the  window  position  adjusted  using  the 
WinSetWindowPos  function  call  which  sends  a WM_SIZE  message  if  the  position  or  size  is  changed. 

The  only  limitation  to  the  size  and  position  specified  for  a window  is  the  number  range  allowed  for 
the  size  and  position  parameters;  that  is,  an  application  can  create  windows  that  are  larger  than  the 
screen  or  that  are  positioned  partially  or  totally  off  the  screen.  However,  the  user  interface  for 
manipulation  of  window  sizes  and  positions  is  affected  if  part  or  all  of  the  window  is  off  the  screen. 

It  is  recommended  that  part  of  the  title  bar  be  left  on  the  screen,  if  the  window  has  one,  to  enable  the 
user  to  move  the  window  around. 

When  a WC_MENU  window  is  created  with  this  call,  pCtIData  is  assumed  to  be  a menu  template, 
which  is  used  to  create  the  menu.  If  pCtIData  is  NULL,  an  empty  menu  is  created. 


Related  Functions 

• WinCalcFrameRect 

• WinCreateFrameControls 

• WinCreateStdWindow 

• WinDefWindowProc 

• WinDestroyWindow 

• WinQueryClassInfo 

• WinQueryClassName 

• WinRegisterClass 

• WinSubclassWindow 


Related  Messages 

• WM_ADJUSTWINDOWPOS 

• WM_CREATE 

• WM_FORMATFRAME 

• WM_SIZE 
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Example  Code 

This  example  creates  a list  box  window  named  'new  button'  as  a child  of  the  Desk  Top,  located  at 
(0,0)  of  size  200x100.  window. 


Idefine  INCLJIINWINDOWMGR  /*  Window  Manager  Functions  */ 

Idefine  INCLJIINLISTBOXES  /*  List  Box  definitions  */ 

linclude  <os2.h> 

HWND  hwnd;  /*  cursor  display  window  */ 

ULONG  Buttonld;  /*  window  id  (app  supplied)  */ 

ULONG  fl Style;  /*  window  style  */ 

flStyle  = WS_VISIBLE;  /*  create  window  visible  */ 

/*  create  button  window  */ 

hwnd  = WinCreateWindow(HWND_DESKTOP,  /*  parent  window  */ 

WC_LISTBOX,  /*  class  name  */ 

"new  button",  /*  window  text  */ 

flStyle,  /*  window  style  */ 

0,  0,  /*  position  (x,y)  */ 

200,  100,  /*  size  (width, height)  */ 

NULLHANDLE,  /*  owner  window  */ 

HWND_T0P,  /*  sibling  window  */ 

Buttonld,  /*  window  id  */ 

NULL,  /*  control  data  */ 

NULL);  /*  presentation  parms  */ 
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WinDdelnitiate  - 

Dynamic  Data  Exchange  Initiate  (NLS) 


#define  INCL_WINDDE  /*  Or  use  INCL_WIN  or  INCL_PM  */ 


BOOL  WinDdelnitiate  (HWND  hwndCllent,  PSZ  pszAppName,  PSZ  pszTopIcName, 
PCONVCONTEXT  pContext) 


This  function  is  issued  by  a client  application  to  one  or  more  other  applications,  to  request  initiation 
of  a dynamic  data  exchange  conversation  with  a national  language  conversation  context. 


Parameters 

hwndCllent  (HWND)  - input 
Client’s  window  handle. 

This  window  will  typically  not  be  visible. 

pszAppName  (PSZ)  - input 
Application  name. 

This  is  the  name  of  the  desired  server  application.  If  it  is  a zero-length  string,  any  application 
can  respond. 

Application  names  may  not  contain  slashes  or  backslashes. 

pszTopIcName  (PSZ)  - input 
Topic  name. 

This  is  the  name  of  the  desired  topic.  If  it  is  a zero-length  string,  each  responding  application 
will  respond  once  for  each  topic  which  it  can  support. 

pContext  (PCONVCONTEXT)  - input 
Conversation  context. 


Returns 

Success  indicator: 

TRUE  Successful  completion.  The  WM_DDE_INITIATE  message  is  successfully  sent  to  all 
appropriate  windows. 

FALSE  Error  occurred. 

Remarks 

This  function  sends  a WM_DDE_INITIATE  message  to  all  top  level  frame  windows.  These  are 
windows  registered  with  CS_FRAME,  whose  parent  is  the  desktop  window.  No  message  is  sent  to 
object  windows. 

The  WinDdelnitiate  function  does  not  return  to  the  client  application  until  all  receiving  applications 
have,  in  sequence,  processed  the  WM_DDE_INITIATE  message,  and  the  client  application  has 
received  all  the  corresponding  WM_DDE_INITIATEACK  messages  (see  WinDdeRespond). 

To  support  DDE  conversations  between  applications  running  in  different  memory  models  (16-bit  and 
32-bit)  it  is  necessary  to  process  all  DDE  messages  in  the  application  window  procedure.  The  use  of 
the  WinDispatchMsg  function  ensures  that  conversion  is  performed  on  memory  or  segment 
addresses. 
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Dynamic  Data  Exchange  Initiate  (NLS) 


Related  Functions 

• WinDdePostMsg 

• WinDdeRespond 

Related  Messages 

• WM_DDE_INITIATE 

• WM_DDE_INITIATEACK 

Example  Code 

This  example  uses  WinDdelnitiate  to  initiate  - during  the  creation  of  a client  window  - a dynamic  data 
exchange  (DDE)  conversation  with  any  available  server  applications,  asking  that  the  server 
applications  respond  for  each  topic  they  can  support.  It  also  allocates  the  shared  memory  that  will 
be  used  once  the  conversation  is  established. 


fdefine  INCL_WINDDE  /*  Window  DOE  Functions  */ 
fdefine  INCL_DOSMEMMGR  /*  Memory  Manager  values  */ 
#include  <os2.h> 

BOOL  f Success;  /*  success  indicator  */ 
HWND  hwndClient;  /*  client  window  */ 
char  pszAppName [15] ="";/*  server  application  */ 
char  pszTopicName[15]=‘1";/*  topic  */ 
CONVCONTEXT  Context; 

PDDESTRUCT  pddeData;  /*  DDE  structure  */ 


case  WM_CREATE: 

/*  issue  DDE  initialize  call  */ 

fSuccess  = WinDdeInitiate(hwndClient,  pszAppName, 

pszTopicName,  &Context); 

/*  allocate  shared  memory  for  conversation  data  */ 
DosAl 1 ocSharedMem ( ( PVOID)pddeData , "DDESHAREMEM" , 
sizeof(DDESTRUCT)  + 50, 

PAG_READ  | PAG_WRITE  | PAG_COMMIT  | 
OBJ_GIVEABLE  | OBJ_GETTABLE) ; 
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Dynamic  Data  Exchange  Post  Message  (NLS) 


#define  INCL_WINDDE  /*  Or  use  INCL_WIN  or  INCL_PM  */ 


BOOL  WinDdePostMsg  (HWND  hwndTo,  HWND  hwndFrom,  USHORT  usMsgid, 
PDDESTRUCT  pData,  ULONG  ulOptlons) 


This  function  is  issued  by  an  application  to  post  a message  to  another  application  with  which  it  is 
carrying  out  a dynamic  data  exchange  conversation  with  a national  language  conversation  context. 


Parameters 

hwndTo  (HWND)  - input 
Window  handle  of  target. 

hwndFrom  (HWND)  - input 

Window  handle  of  originator. 

usMsgid  (USHORT)  - input 
Message  identifier. 

Identifies  the  message  to  be  posted. 

The  following  messages  are  valid: 

WM_DDE_ACK 

WM_DDE_ADVISE 

WM_DDE_DATA 

WM_DDE_EXECUTE 

WM_DDE_POKE 

WM_DDE_REQUEST 

WM_DDE_TERMINATE 

WM_DDE_UNADVISE. 

pData  (PDDESTRUCT)  - input 
DDE  structure  passed. 

Points  to  a DDESTRUCT  structure.  This  parameter  is  always  sent  to  an  application  as  a 16-bit 
address.  For  a 32-bit  application,  a conversion  to  a flat  address  is  required.  Use  public  macros 
DOSFLATTOSEL  or  DOSSELTOFLAT  to  convert  0:32  to  16:16  or  vice  versa. 

ulOptlons  (ULONG)  - input 
Options. 

DDEPM_RETRY  This  controls  what  happens  if  the  message  cannot  be  posted  because  the 
destination  queue  is  full. 

If  this  option  is  set,  then  message  posting  is  retried  at  1-second  intervals, 
until  the  message  is  posted  successfully.  In  this  case,  this  function 
dispatches  any  messages  in  the  queue  of  the  application  issuing  this 
function,  by  calling  the  WinPeekMsg  and  WinDispatchMsg  functions  in  a 
loop,  so  that  messages  sent  by  other  applications  can  be  received.  This 
means  that  the  application  can  continue  to  receive  DDE  messages  (or  other 
kinds  of  messages),  while  attempting  to  post  DDE  messages,  thereby 
preventing  deadlock  between  two  applications  whose  queues  are  full  and 
who  are  both  attempting  to  post  a message  to  each  other  with  this  option 
set. 
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Dynamic  Data  Exchange  Post  Message  (NLS) 


Applications  which  rely  on  inspecting  messages  prior  to  issuing  the 
WinPeekMsg  function  can  either,  use  the  WinSetHook  function  and  detect  the 
above  situation  in  the  invoked  hook  procedure  by  testing  the 
MSGF_DDEPOSTMSG  value  of  the  usContext  parameter,  or  not  use  this 
option,  in  order  to  avoid  the  deadlock  situation. 

If  this  option  is  not  set,  then  this  function  returns  FALSE  without  retrying. 

Note:  If  the  message  posting  fails  for  any  other  reason  (for  example,  an 

invalid  window  handle  is  specified),  this  function  returns  FALSE  even 
if  this  option  has  been  selected. 

DDEPM_NOFREE  Indicates  that  the  receiver  is  not  to  free  the  memory  on  behalf  of  the 
originator. 

Returns 

Success  indicator: 

TRUE  Successful  completion 
FALSE  Error  occurred. 

Remarks 

To  support  DDE  conversations  between  applications  running  in  different  memory  models  (16-bit  and 
32-bit)  it  is  necessary  to  process  all  DDE  messages  in  the  application  window  procedure.  The  use  of 
the  WinDispatchMsg  function  ensures  that  conversion  is  performed  on  memory  or  segment 
addresses. 

Related  Functions 

• WinDdelnitiate 

• WinDdeRespond 

Related  Messages 

• WM_DDE_ACK 

• WM_DDE_ADVISE 

• WM_DDE_DATA 

• WM_DDE_EXECUTE 

• WM_DDE_POKE 

• WM_DDE_REQUEST 

• WM_DDE_TERMINATE 

• WM_DDE_UNADVISE 
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Dynamic  Data  Exchange  Post  Message  (NLS) 


Example  Code 

This  example  uses  WinDdePostMsg  to  request  a security  item  from  the  server  once  it  has  received 
an  acknowledgement  (via  WM_DDEINITIATEACK)  to  the  WinDdelnitiate  call.  Note  the  use  of  the 
shared  memory  segment  to  pass  and  receive  necessary  information. 


fdefine  INCL_WINDDE  /*  Window  DDE  Functions  */ 
fdefine  INCL_DOSMEMMGR  /*  Memory  Manager  values  */ 
finclude  <os2.h> 

BOOL  f Success;  /*  success  indicator  */ 
HWND  hwndClient;  /*  client  window  */ 
HWND  hwndServer;  /*  server  window  */ 
char  pszAppName[15]="" ;/*  server  application  */ 
char  pszTopicName[15]="";/*  topic  */ 
HWND  hwndTo;  /*  target  window  */ 
HWND  hwndFrom;  /*  source  window  */ 
USHORT  usMsgld;  /*  message  id  */ 
BOOL  fRetry;  /*  retry  indicator  */ 
CONVCONTEXT  Context; 

PDDESTRUCT  pddeData;  /*  DDE  structure  */ 
MRESULT  mresReply;  /*  message  return  data  */ 


case  WM  CREATE: 

fSuccess  = WinDdeInitiate(hwndClient,  pszAppName, 

pszTopicName,  &Context); 

DosAl 1 ocSharedMem( ( PVOID) pddeData , "DDESHAREMEM" , 
sizeof(DDESTRUCT)  + 50, 

PAG_READ  | PAG_WRITE  | PAG_C0MMIT  | 

0BJ_GIVEABLE  | 0BJ_GETTABLE) ; 

case  WM_DDE_INITIATEACK: 

/*  issue  a request  message  to  DDE  partner  */ 
usMsgld  = WM_DDE_REQUEST ; 

/*  initialize  DDE  conversation  structure  */ 
pddeData. cbData  = sizeof(DDESTRUCT) ; /*  Total  length  */ 

pddeData. fsStatus  = DDE_FACK;  /*  Status  - positive  ack  */ 
pddeData. us Format  = DDEFMT_TEXT;  /*  Data  format  */ 

pddeData. offszItemName  = sizeof(DDESTRUCT) ;/*  Offset  to  item  */ 

/*  set  name  of  item  to  'Security1,  copying  the  information  to 
the  shared  memory  at  the  end  of  pddeData  */ 
strcpy((BYTE  *)pddeData  + pddeData->offszItem, 
SZDDESYS_ITEM_SECURITY ) ; 

/*  Offset  to  beginning  of  data  (notice  additional  offset  due 
to  item  information)  */ 

pddeData. of fabData  = sizeof(DDESTRUCT)  + 

strlen(SZDDESYS_ITEM_SECURITY) ; 

/*  set  name  of  item  to  'Security',  copying  the  information  to 
the  shared  memory  at  the  end  of  pddeData  */ 
strcpy((BYTE  *)pddeData  + pddeData->offszItem, 
SZDDESYS_ITEM_SECURITY) ; 

fSuccess  = WinDdePostMsg(hwndTo,  hwndFrom,  usMsgld,  pddeData, 

fRetry); 
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Dynamic  Data  Exchange  Respond  (NLS) 


#define  INCL_WINDDE  /*  Or  use  INCL_WIN  or  INCL_PM  */ 


M RESULT  WinDdeRespond  (HWND  hwndCllent,  HWND  hwndServer,  PSZ  pszAppName, 

PSZ  pszTopicName,  PCONVCONTEXT  pContext) 


This  function  is  issued  by  a server  application  to  indicate  that  it  can  support  a dynamic  data 
exchange  conversation  on  a particular  topic  with  a national  language  conversation  context. 


Parameters 

hwndCllent  (HWND)  - input 
Client’s  window  handle. 

hwndServer  (HWND)  - input 
Server’s  window  handle. 

If  a server  application  is  responding  for  more  than  one  topic,  it  must  use  a different  window  for 
each  topic. 

pszAppName  (PSZ)  - input 
Application  name. 

This  is  the  name  of  the  responding  server  application.  It  must  not  be  a zero-length  string. 

Application  names  may  not  contain  slashes  or  backslashes. 

pszTopicName  (PSZ)  - input 
Topic  name. 

This  is  the  name  of  the  topic  which  the  server  is  willing  to  support.  It  must  not  be  a zero-length 
string. 

pContext  (PCONVCONTEXT)  - input 
Conversation  context. 


Returns 

Message  return  data. 


Remarks 

This  function  is  issued  by  a server  application  after  receiving  a WM_DDE_INITIATE  message  that 
identifies  this  server  application  (or  indicates  that  any  application  can  respond),  and  also  either 
identifies  a particular  topic  which  the  server  can  support,  or  asks  for  all  supported  topics  (see 
WinDdelnitiate).  This  function  sends  a WM_DDE_INITIATEACK  message  back  to  the  client,  that  is  the 
sender  of  the  WM_DDE_INITIATE  message. 

If  the  server  application  can  respond,  it  issues  this  function  once  if  a specific  topic  was  requested,  or 
once  for  each  topic  which  it  can  support,  if  all  supported  topics  were  requested. 

A DDE  conversation  is  initiated  each  time  this  function  is  successfully  issued.  The  client  is  expected 
to  terminate  all  unwanted  conversations.  Once  a conversation  is  initiated,  it  is  controlled  by  the 
client  issuing  WinDdePostMsg  functions. 

To  support  DDE  conversations  between  applications  running  in  different  memory  models  (16-bit  and 
32-bit)  it  is  necessary  to  process  all  DDE  messages  in  the  application  window  procedure.  The  use  of 
the  WinDispatchMsg  function  ensures  that  conversion  is  performed  on  memory  or  segment 
addresses. 
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Dynamic  Data  Exchange  Respond  (NLS) 


Related  Functions 

• WinDdelnitiate 

• WinDdePostMsg 

Related  Messages 

• WM_DDE_INITIATE 

• WM_DDE_INITIATEACK 

Example  Code 

This  example  uses  WinDdeRespond  to  respond  to  an  initiate  message  (WM_DDEINITIATE)  generated 
by  the  client  window  issuing  WinDdelnitiate.  Here,  the  server  responds  as  a DDE  Server  that 
supports  a System  topic. 


fdefine  INCL_WINDDE  /*  Window  DDE  Functions  */ 

finclude  <os2.h> 

HWND  hwndClient;  /*  client  window  */ 

HWND  hwndServer;  /*  server  window  */ 

char  pszAppName[15]="DDE  Server";  /*  server  application  */ 

char  pszTopicName[15]=SZDDESYS_T0PIC;  /*  topic  ('System')  */ 
MRESULT  mresReply;  /*  message  return  data  */ 

CONVCONTEXT  Context; 
case  WM_DDE_INITIATE: 


mresReply  = WinDdeRespond (hwndClient,  hwndServer,  pszAppName, 

pszTopicName,  &Context); 
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Default  Dialog  Procedure 


#define  INCL_WINDIALOGS  /*  Or  use  INCL_WIN  or  INCL_PM.  Also  in  COMMON  section  7 


M RESULT  WinDefDIgProc  (HWND  hwndDIg,  ULONG  ulMsgld,  MPARAM  mpParaml, 

M PAR  AM  mpParam2) 


This  function  invokes  the  default  dialog  procedure  with  hwndDIg,  ulMsgid,  mpParaml,  and 
mpParam2. 


Parameters 

hwndDIg  (HWND)  - input 
Dialog-window  handle. 

ulMsgld  (ULONG)  - input 
Message  identity. 

mpParaml  (MPARAM)  - input 
Parameter  1. 

mpParam2  (MPARAM)  - input 
Parameter  2. 


Returns 

Message-return  data. 

Possible  returns  from  WinGetLastError 

PMERR  INVALID  HWND  An  invalid  window  handle  was  specified. 

Remarks 

The  action  taken  by  the  default  dialog  procedure  is  such  that  the  values  passed  in  mpParaml  and 
mpParam2,  and  the  values  returned  in  mresReply  are  defined  for  each  ulMsgid. 

The  default  dialog  procedure  provides  default  processing  for  any  dialog  window  messages  that  an 
application  chooses  not  to  process.  It  can  be  used  to  ensure  that  every  message  is  processed  and  is 
called  with  the  same  parameters  that  were  received  by  the  dialog  procedure. 

The  action  of  the  WinDefDIgProc  function  on  receiving  messages  is  precisely  the  same  as  for  the 
frame  window  procedure  except  for  WM_CLOSE  messages  where  WinDismissDIg  will  be  called.  If  an 
application  processes  a message  instead  of  sending  it  to  the  WinDefDIgProc  function,  it  may  be 
required  to  perform  some  or  all  of  the  frame  window  procedure  actions  for  itself. 


Related  Functions 

• WinCreateDIg 

• WinDismissDIg 

• WinDIgBox 

• WinGetDIgMsg 

• WinLoadDIg 

• WinProcessDIg 
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Default  Dialog  Procedure 


Example  Code 

This  example  shows  a typical  dialog  box  procedure.  A switch  statement  is  used  to  process 
individual  messages.  All  messages  not  processed  are  passed  on  to  the  WinDefDIgProc  function. 


Idefine  INCL_WINDIALOGS  /*  Window  Dialog  Mgr  Functions  */ 

linclude  <os2.h> 


MRESULT  AboutDlg(HWND  hwnd,  ULONG  ulMessage,  MPARAM  mpl, 

MPARAM  mp2) 


{ 


switch  (ulMessage)  { 


/* 

* Process  whatever  messages  you  want  here  and  send  the  rest 

* to  WinDefDIgProc. 

*/ 


} 


default: 

return  (WinDefDlgProc(hwnd,  ulMessage,  mpl,  mp2)); 
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WinDefFileDIgProc  - 
Standard  File  Dialog  Default  Procedure 


#define  INCL_WINSTDFILE 


M RESULT  WinDefFileDIgProc  (HWND  hwndOlg,  ULONG  ulMsgld,  M PAR  AM  mpParaml, 

MPARAM  mpParam2) 


This  function  is  the  default  dialog  procedure  for  the  file  dialog. 


Parameters 

hwndDIg  (HWND)  - input 
Dialog-window  handle. 

ulMsgld  (ULONG)  - input 
Message  identity. 

mpParaml  (MPARAM)  - input 
Parameter  1. 

mpParam2  (MPARAM)  - input 
Parameter  2. 


Returns 

Message-return  data. 


Remarks 

All  unprocessed  messages  in  a custom  dialog  procedure  should  be  passed  to  the  default  file  dialog 
procedure  so  that  the  dialog  can  implement  its  default  behavior. 

Example  Code 

This  example  uses  the  default  dialog  procedure  for  the  file  dialog  to  cause  default  processing  of 
unprocessed  dialog  messages. 

fdefine  INCL_WINSTDFILE  /*  Window  Standard  File  Functions  */ 

finclude  <os2.h> 

MRESULT  MyFileDlgProc(HWND  hwndDIg,  ULONG  ulMsgid,  MPARAM  Paraml, 

MPARAM  Param2) 

{ 

switch(ulMsgid) 

{ 

f ************************************************************** j 

/*  Process  user-supported  messages  */ 

/**************************************************************  / 


default: 

return  (WinDefFileDlgProc(hwndDlg,  ulMsgid,  Paraml,  Param2)); 

} 
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Standard  Font  Dialog  Default  Procedure 


#define  INCL_WINSTDFONT 


MRESULT  WinDefFontDIgProc  (HWND  hwndDIg,  ULONG  ulMsgld,  M PAR  AM  mpParaml, 

MPARAM  mpParam2) 


This  function  is  the  default  dialog  procedure  for  the  font  dialog. 


Parameters 

hwndDIg  (HWND)  - input 
Dialog-window  handle. 

ulMsgld  (ULONG)  - input 
Message  identity. 

mpParaml  (MPARAM)  - input 
Parameter  1 . 

mpParam2  (MPARAM)  - input 
Parameter  2. 


Returns 

Message-return  data. 


Remarks 

All  unprocessed  messages  in  a custom  dialog  procedure  should  be  passed  to  the  default  font  dialog 
procedure  so  that  the  dialog  can  implement  its  default  behavior. 

Example  Code 

This  example  uses  the  default  dialog  procedure  for  the  font  dialog  to  cause  default  processing  of 
unprocessed  dialog  messages. 

Idefine  INCL_WINSTDFONT  /*  Window  Standard  Font  Functions  */ 

linclude  <os2.h> 

MRESULT  My FontDl gProc ( HWND  hwndDIg,  ULONG  ulMsgid,  MPARAM  Paraml, 

MPARAM  Param2) 

{ 

switch(ulMsgid) 

{ 

j ************************************************************** j 

/*  Process  user-supported  messages  */ 

y**************************************************************  j 


default: 

return  (WinDefFontDlgProc(hwndDlg,  ulMsgid,  Paraml,  Param2)); 

} 


8-88  PM  Programming  Reference 


WinDefWindowProc  - 
Default  Window  Procedure 


#define  INCL_WINWINDOWMGR  /*  Or  use  INCL_WIN  or  INCL_PM.  Also  in  COMMON  section  */ 


MRESULT  WinDefWindowProc  (HWND  hwnd,  ULONG  ulMsgld,  M PAR  AM  mpParaml, 

M PAR  AM  mpParam2) 


This  function  invokes  the  default  window  procedure. 


Parameters 

hwnd  (HWND)  - input 
Window  handle. 

ulMsgld  (ULONG)  - input 
Message  identity. 

mpParaml  (MPARAM)  - input 
Parameter  1 . 

mpParam2  (MPARAM)  - input 
Parameter  2. 


Returns 

Message-return  data. 

Possible  returns  from  WinGetLastError 

PMERR  INVALID  HWND  An  invalid  window  handle  was  specified. 

Remarks 

The  default  window  provides  default  processing  for  any  window  messages  that  an  application 
chooses  not  to  process.  It  can  be  used  to  ensure  that  every  message  is  processed.  This  function 
should  be  made  with  the  same  parameters  as  those  received  by  the  window  procedure. 

The  action  taken  by  the  default  window  procedure,  the  values  passed  in  mpParaml,  mpParam2  and 
the  values  returned  in  mresReply  are  defined  for  each  ulMsgid.  (See  Chapter  11,  “Introduction  to 
Message  Processing”  on  page  11-1.) 


Related  Functions 

• WinCalcFrameRect 

• WinCreateFrameControls 

• WinCreateStd  Window 

• WinCreateWindow 

• WinDestroyWindow 

• WinQueryClassinfo 

• WinQueryClassName 

• WinRegisterClass 

• WinSubclassWindow 
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WinDefWindowProc  - 
Default  Window  Procedure 

Example  Code 

This  example  uses  the  default  window  procedure,  called  by  WinDefWindowProc,  for  default 
processing  of  non  supported  window  messages. 

fdefine  INCL_WINWINDOWMGR  /*  Window  Manager  Functions  */ 

finclude  <os2.h> 

MRESULT  Gener i cWndProc ( HWND  hwnd,  ULONG  ulMsgid,  MPARAM  mpl, 

MPARAM  mp2) 

{ 

switch(ulMsgid) 

{ 

/* 

. process  user  supported  messages 

V 

default: 

return  (WinDefWindowProc(hwnd,  ulMsgid,  mpl,  mp2)); 

} 

} 


8-90  PM  Programming  Reference 


WinDeleteAtom  - 
Delete  Atom 


#define  INCL_WINATOM  /*  Or  use  INCL_WIN  or  INCL_PM  */ 


ATOM  WinDeleteAtom  (HATOMTBL  hatomtblAtomTbl,  ATOM  atom) 


This  function  deletes  an  atom  from  an  atom  table. 

Parameters 

hatomtblAtomTbl  (HATOMTBL)  - input 
Atom-table  handle. 

This  is  the  handle  returned  from  a previous  WinCreateAtomTable  or  WinQuerySystemAtomTable 
function. 

atom  (ATOM)  - input 

Atom  identifying  the  atom  to  be  deleted. 


Returns 

Return  code: 

0 Call  successful 

Other  The  call  fails  and  the  atom  has  not  been  deleted,  in  which  case  this  is  equal  to  the  atom 
parameter. 

Possible  returns  from  WinGetLastError 

PMERRJNVALIDHATOMTBL 
PMERRJNVALIDATOM 

Remarks 

If  the  passed  atom  is  an  integer  atom,  0 is  returned.  If  it  is  not  an  integer  atom  and  it  is  a valid  atom 
for  the  given  atom  table,  that  is,  it  has  an  atom  name  and  use  count,  its  use  count  is  decremented  by 
one  and  0 is  returned.  If  the  use  count  has  been  decremented  to  zero,  the  atom  name  and  use  count 
are  removed  from  the  atom  table. 

Related  Functions 

• WinAddAtom 

• WinCreateAtomTable 

• WinDestroyAtomTable 

• WinFindAtom 

• WinQueryAtomLength 

• WinQueryAtomName 

• WinQueryAtomllsage 

• WinQuerySystemAtomTable 


An  invalid  atom-table  handle  was  specified. 

The  specified  atom  does  not  exist  in  the  atom  table. 
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WinDeleteAtom 
Delete  Atom 


Example  Code 

This  example  deletes  a newly  created  atom  in  an  Atom  Table  based  on  the  atom  value  returned  by 
WinAddAtom. 


Idefine  INCL.WINATOM  /*  Window  Atom  Functions  */ 
linclude  <os2.h> 

ATOM  atom;  /*  new  atom  value  */ 
ATOM  atomDelete;  /*  result  of  atom  delete  */ 
HATOMTBL  hatomtbl AtomTbl ; /*  atom-table  handle  */ 
char  pszAtomName[10] ; /*  atom  name  */ 


ULONG  ul Initial  = 0;  /*  initial  atom  table  size  (use  default)*/ 

ULONG  ulBuckets  = 0;  /*  size  of  hash  table  (use  default)  */ 

/*  create  atom  table  of  default  size  */ 

hatomtbl AtomTbl  = WinCreateAtomTable(ul Initial , ulBuckets); 

/*  define  name  for  new  atom  and  add  to  table  */ 

s t rcpy (ps  z AtomName , " newatom " ) ; 

atom  = WinAddAtom(hatomtblAtomTbl , pszAtomName); 

atomDelete  = Wi nDeleteAtom (hatomtbl AtomTbl , atom); 
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WinDeleteLboxItem  - 
Delete  Listbox  Item 


#define  INCL_WINWINDOWMGR  /*  Or  use  INCL_WIN  or  INCL_PM  7 


SHORT  WinDeleteLboxItem  (HWND  hwndLbox,  SHORT  slndex) 


This  macro  deletes  the  indexed  item  from  the  List  Box.  It  returns  the  number  of  items  left. 

Parameters 

hwndLbox  (HWND)  - input 
Listbox  handle. 

slndex  (SHORT)  - input 
Index  of  the  listbox  item. 


Returns 

Number  of  items  left. 


Remarks 

This  macro  expands  to: 

fdefine  WinDeleteLboxItem(hwndLbox,  slndex) 

( (SHORT)Wi nSendMsg ( hwndLbox , 

LM_DELETEITEM, 
MPFROMSHORT(sIndex) , 

(MPARAM) NULL) ) 

This  function  requires  the  existence  of  a message  queue. 


Related  Functions 

• WinSendMsg 


Related  Messages 

• LM_DELETEITEM 
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WinDeleteLboxItem 
Delete  Listbox  Item 


Example  Code 

This  example  responds  to  an  item  in  the  list  box  being  selected  (LN_SELECT,  WM_CONTROL 
message)  by  deleting  the  selected  item  using  WinDeleteLboxItem. 


fdefine  INCL_WINWINDOWMGR  /*  Window  Manager  Functions  */ 
Idefine  INCL_WINLISTBOXES  /*  Window  List  Box  definitions  */ 
linclude  <os2.h> 

SHORT  slndex;  /*  selected  item  index  */ 
SHORT  sLeft;  /*  items  left  after  delete  */ 
HWND  hwndLbox;  /*  list  box  window  handle  */ 
MPARAM  mpl;  /*  Parameter  1 (recti  structure)  */ 
MPARAM  mp2;  /*  Parameter  2 (frame  boolean)  */ 


case  WM_C0NTR0L: 

/*  switch  on  control  code  */ 
swi tch (SH0RT2FR0MMP (mpl) ) 

{ 

case  LN_SELECT: 

hwndLbox  = HWNDFR0MMP(mp2) ; 

/*  query  index  of  selected  item  */ 
slndex  = WinQueryLboxSelectedltem(hwndLbox); 

/*  delete  selected  listbox  item  */ 

sLeft  = WinDeleteLboxItem(hwndLbox,  slndex); 

break; 

} 
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WinDeleteLibrary  - 
Delete  Library 


#define  INCL_WINLOAD  /*  Or  use  INCL_WIN  or  INCL_PM  */ 


BOOL  WinDeleteLibrary  (HAB  hab,  HUB  hllbLIbhandle) 


This  function  deletes  the  library  hlibLibhandle,  which  is  previously  loaded  by  the  WinLoadLibrary 
function. 

Parameters 

hab  (HAB)  - input 

Anchor-block  handle. 

hllbLIbhandle  (HUB)  - input 
Library  handle  to  be  deleted. 


Returns 

Library-deleted  indicator. 

TRUE  Library  successfully  deleted 
FALSE  Library  not  successfully  deleted. 

Related  Functions 

• WinDeleteProcedure 

• WinLoadLibrary 

• WinLoadProcedure 


Example  Code 

This  example  deletes  the  library  identified  by  the  library  handle  returned  from  WinLoadLibrary. 


fdefine  INCL_WINLOAD  /*  Window  Load  Functions  */ 

finclude  <os2.h> 


BOOL 

fSuccess; 

/*  success  indicator 

HAB 

hab; 

/*  anchor-block  handle 

HLIB 

hlib; 

/*  library  handle 

fSuccess  = WinDeleteLibrary  (hab,  hlib); 


*/ 

*/ 

*/ 
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WinDeleteProcedure 
Delete  Procedure 


#define  INCL_WINLOAD  /*  Or  use  INCL_WIN  or  INCL_PM  */ 


BOOL  WinDeleteProcedure  (HAB  hab,  PFNWP  pwndproc) 


This  function  deletes  the  window  or  dialog  procedure  that  was  previously  loaded  using  the 
WinLoadProcedure  function. 

Parameters 

hab  (HAB)  - input 

Anchor-block  handle. 

pwndproc  (PFNWP)  - input 

Window  procedure  identifier  to  be  deleted. 


Returns 

Procedure-deleted  indicator. 

TRUE  Procedure  successfully  deleted 
FALSE  Procedure  not  successfully  deleted. 

Related  Functions 

• WinDeleteLibrary 

• WinLoadLibrary 

• WinLoadProcedure 

Example  Code 

This  example  deletes  the  procedure  identified  by  the  procedure  pointer  returned  from 
WinLoadProcedure. 


Idefine  INCLJIINLOAD  /*  Window  Load  Functions  */ 
linclude  <os2.h> 

BOOL  f Success;  /*  success  indicator  */ 
PFNWP  pWndproc;  /*  procedure  pointer  */ 
HAB  hab;  /*  anchor-block  handle  */ 


fSuccess  = WinDeleteProcedure(hab,  pWndproc); 
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WinDeregisterObjectClass  - 
Deregister  Workplace  Object  Class 


#define  INCL_WINWORKPLACE 


BOOL  WinDeregisterObjectClass  (PSZ  pszClassName) 


The  WinDeregisterObjectClass  function  deregisters  (removes)  a workplace  object  class. 

Parameters 

pszClassName  (PSZ)  - input 

A pointer  to  a zero-terminated  string  which  contains  the  name  of  the  object  class  being  removed 
from  the  workplace. 


Returns 

Success  indicator: 

TRUE  Successful  completion 
FALSE  Error  occurred. 

Remarks 

Workplace  object  classes  are  not  deleted  unless  the  application  issues  a WinDeregisterObjectClass. 
Object  classes  will  be  automatically  registered  when  a dynamic-link  library  containing  an  object 
definition  is  added  to  the  system.  The  only  advantage  of  deregistering  an  object  class  is  to  optimize 
the  system  performance.  All  registered  classes  are  maintained  in  the  OS2.INI  and  are  cached  upon 
system  initialization.  If  the  class  is  no  longer  needed,  it  should  be  removed. 


Related  Functions 

• WinCreateObject 

• WinRegisterObjectClass 

• WinReplaceObjectClass 
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WinDestroyAccelTable  - 
Destroy  Accelerator  Table 


#define  INCL_WINACCELERATORS  /*  Or  use  INCL_WIN  or  INCL_PM  */ 


BOOL  WinDestroyAccelTable  (HACCEL  haccelAccel) 


This  function  destroys  an  accelerator  table. 


Parameters 

haccelAccel  (HACCEL)  - input 
Accelerator-table  handle. 


Returns 

Success  indicator: 

TRUE  Successful  completion 
FALSE  Error  occurred. 

Possible  returns  from  WinGetLastError 

PMERR  INVALID  HACCEL  An  invalid  accelerator-table  handle  was  specified. 

Remarks 

Before  an  application  is  terminated,  it  should  call  the  WinDestroyAccelTable  function  for  every 
accelerator  table  that  is  created  with  the  WinCreateAccelTable  function. 

Related  Functions 

• WinCopyAccelTable 

• WinCreateAccelTable 

• WinLoadAccelTable 

• WinOueryAccelTable 

• WinSetAccelTable 

• WinTranslateAccel 

Example  Code 

This  example  destroys  an  accelerator-table  based  on  the  handle  returned  from  either 
WinCreateAccelTable  or  WinLoadAccelTable. 

fdefine  INCL_WINACCELERATORS  /*  Window  Accelerator  Functions  */ 
finclude  <os2.h> 

HACCEL  hAccel ; /*  Accelerator-table  handle  */ 

BOOL  f Success;  /*  success  indicator  */ 

fSuccess  = WinDestroyAccelTable(hAccel ) ; 
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WinDestroyAtomTable  - 
Destroy  Atom  Table 


#define  INCL_WINATOM  /*  Or  use  INCL_WIN  or  INCL_PM  */ 


HATOMTBL  WinDestroyAtomTable  (HATOMTBL  hatomtblAtomTbl) 


This  function  destroys  an  atom  table,  which  is  created  by  WinCreateAtomTable 


Parameters 

hatomtblAtomTbl  (HATOMTBL)  - input 
Atom-table  handle. 

This  is  the  handle  returned  from  a previous  call  to  the  WinCreateAtomTable  function.  If  NULL 
then  this  function  does  nothing. 


Returns 

Return  code: 

0 Function  successful. 

Other  The  call  fails  and  the  atom  table  has  not  been  destroyed,  in  which  case  this  is  equal  to 
the  hatomtblAtomTbl  parameter. 

Possible  returns  from  WinGetLastError 

PMERRINVALIDHATOMTBL  An  invalid  atom-table  handle  was  specified. 

Remarks 

This  function  makes  no  attempt  to  ensure  that  the  handle  to  the  atom  table  is  not  reused  by  a later 
call  to  the  WinCreateAtomTable  function. 

The  system  atom  table  (see  the  WinQuerySystemAtomTable  function)  cannot  be  destroyed. 


Related  Functions 

• WinAddAtom 

• WinCreateAtomTable 

• WinDeleteAtom 

• WinFindAtom 

• WinQueryAtomLength 

• WinQueryAtomName 

• WinQueryAtomUsage 

• WinQuerySystemAtomTable 
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WinDestroyAtomTable 
Destroy  Atom  Table 


Example  Code 

This  example  destroys  an  Atom  Table  of  one  atom,  based  on  its  handle,  which  is  returned  by 
WinCreateAtomTable. 


Idefine  INCL_WINATOM  /*  Window  Atom  Functions  */ 
finclude  <os2.h> 

ATOM  atom;  /*  new  atom  value  */ 
HATOMTBL  hatomtblAtomTbl;  /*  atom-table  handle  */ 
HATOMTBL  hatomtbl Destroy;  /*  result  of  destroy  table  */ 
char  pszAtomName [10] ; /*  atom  name  */ 
USHORT  uslnitial  = 0;  /*  initial  atom  table  size  (use  default)*/ 
USHORT  usBuckets  = 0;  /*  size  of  hash  table  (use  default)  */ 


/*  create  atom  table  of  default  size  */ 

hatomtblAtomTbl  = WinCreateAtomTable(usInitial , usBuckets); 

/*  define  name  for  new  atom  and  add  to  table  */ 

strcpy (pszAtomName, "newatom") ; 

atom  = WinAddAtom(hatomtblAtomTbl , pszAtomName); 

hatomtbl Destroy  = WinDestroyAtomTable(hatomtblAtomTbl) ; 
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WinDestroyCursor  - 
Destroy  Cursor 


#define  INCL_WINCURSORS  /*  Or  use  INCL_WIN  or  INCL_PM.  Also  in  COMMON  section  7 


BOOL  WinDestroyCursor  (HWND  hwnd) 


This  function  destroys  the  current  cursor,  if  it  belongs  to  the  specified  window. 

Parameters 

hwnd  (HWND)  - input 

Window  handle  to  which  the  cursor  belongs. 

This  can  be  the  desktop-window  handle  or  HWND_DESKTOP. 

Returns 

Success  indicator: 

TRUE  Successful  completion 
FALSE  Error  occurred. 

Possible  returns  from  WinGetLastError 

PMERRJNVALID  HWND  An  invalid  window  handle  was  specified. 

Remarks 

This  function  has  no  effect  if  the  current  cursor  does  not  belong  to  the  specified  window. 
It  is  not  necessary  to  call  this  function  before  calling  the  WinCreateCursor  function. 

Related  Functions 

• WinCreateCursor 

• WinQueryCursorlnfo 

• WinShowCursor 

Example  Code 

This  example  destroys  the  cursor  defined  for  the  specified  input  window. 

Idefine  INCL_WINCURSORS  /*  Window  Cursor  Functions  */ 

finclude  <os2.h> 

BOOL  f Success;  /*  success  indicator  */ 

HWND  hwnd;  /*  cursor  display  window  */ 

fSuccess  = WinDestroyCursor(hwnd) ; 
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WinDestroyHelpInstance 
Destroy  Help  Instance 


#define  INCL_WINHELP  /*  Or  use  INCL_WIN  or  INCL_PM  */ 


BOOL  WinDestroyHelpInstance  (HWND  hwndHelpInstance) 


This  function  destroys  the  specified  instance  of  the  help  manager. 

Parameters 

hwndHelpInstance  (HWND)  - input 

Handle  of  the  instance  of  the  help  manager  to  be  destroyed. 

This  is  the  handle  returned  by  the  WinCreateHelpinstance  call. 


Returns 

Success  indicator: 

TRUE  Successful  completion 
FALSE  Error  occurred. 

Related  Functions 

• WinAssociateHelpinstance 

• WinCreateHelpinstance 

• WinCreateHelpTable 

• WinLoadHelpTable 

• WinQueryHelpinstance 

Example  Code 

This  example  shows  a typical  main  function  for  an  application  which  uses  help.  Following  creation  of 
the  main  application  window  the  help  manager  is  initialized  and  associated  with  the  window.  The 
help  table  is  defined  in  the  application's  resources.  When  the  window  is  destroyed,  terminating  the 
application,  the  help  instance  is  also  destroyed. 


fdefine  INCL=_WIN 
finclude  <os2.h> 

fdefine  IDHT_APPLICATION  100  /*  id  of  HELP  TABLE  in  resource  file 

*/ 

main(  int  argc,  char  *argv[],  char  *envp[]  ) 

{ 

HAB  hab  = Winlnitial ize(  0 ); 

HMQ  hmq  = WinCreateMsgQueue(  hab,  0 ); 

HWND  hwnd; 

HWND  hwndClient; 

HWND  hwndHelp; 

QMSG  qmsg; 

ULONG  fl Style; 

HELPINIT  helpinit; 

/*  Setup  the  help  initialization  structure  */ 
helpinit. cb  = sizeof(  HELPINIT  ); 
helpinit.ulReturnCode  = 0L; 
helpinit.pszTutorialName  = (PSZ)NULL; 

/*  Help  table  in  application  resource  */ 

hel pi ni t . phtHel pTabl e = (PHELPTABLE)MAKEULONG(  IDHT_APPLICATION,  Dxffff  ); 
helpinit.hmodHelpTableModule  = NULLHANDLE; 
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Win  Destroy  Helplnstance  - 
Destroy  Help  Instance 


/*  Default  action  bar  and  accelerators  */ 
helpinit.hmodAccelActionBarModule  = NULLHANDLE; 
helpinit.idAccelTable  = 0; 
helpinit.idActionBar  = 0; 
helpinit.pszHelpWindowTitle  = "APPNAME  HELP"; 
helpinit.fShowPanel Id  = CMIC_SHOW_PANEL_ID; 
helpinit.pszHelpLibraryName  = "APPNAME.HLP"; 

/*  Register  the  class  */ 
if(  WinRegisterClass(  ...  ) ) 

{ 

/*  create  the  main  window  */ 

fl Style  = FCF_STANDARD; 

hwnd  = WinCreateStdWindow(  ...  ); 

if(  hwnd  ) 

{ 

/*  Create  and  associate  the  help  instance  */ 
hwndHelp  = WinCreateHelpInstance(  hab,  &hel pi ni t ); 

if(  hwndHelp  &&  WinAssociateHelpInstance(  hwndHelp,  hwnd  ) ) 

{ 

/*  Process  messages  */ 

whi 1 e ( WinGetMsg(  hab,  &qmsg,  NULLHANDLE,  0,  0 ) ) 

{ 

WinDispatchMsg(  hab,  &qmsg  ); 

} /*  endwhile  */ 

} 

/*  Remove  help  instance  - note:  add  */ 

/*  WinAssociateHelpInstance(  NULLHANDLE,  hwnd  );  */ 

/*  to  WM_DESTROY  processing  to  remove  the  association.  */ 
WinDestroyHelpInstance(  hwndHelp  ); 

} 

} 

/*  finish  the  cleanup  and  exit  */ 

WinDestroyMsgQueue(  hmq  ); 

WinTerminate(  hab  ); 
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WinDestroyMsgQueue  - 
Destroy  Message  Queue 


#define  INCL_WINMESSAGEMGR  /*  Or  use  INCL_WIN  or  INCL_PM.  Also  in  COMMON  section  */ 


BOOL  WinDestroyMsgQueue  (HMQ  hmq) 


This  function  destroys  the  message  queue. 

Parameters 

hmq  (HMQ)  - input 

Message-queue  handle. 


Returns 

Queue-destroyed  indicator: 

TRUE  Queue  destroyed 
FALSE  Queue  not  destroyed. 

Possible  returns  from  WinGetLastError 

PMERR  INVALID  HMQ  An  invalid  message-queue  handle  was  specified. 

Remarks 

This  function  must  be  called  before  terminating  a thread  or  an  application.  Only  the  thread  that 
called  WinCreateMsgQueue  may  call  this  function  with  that  handle. 


Related  Functions 

• WinCancelShutdown 

• WinBroadcastMsg 

• WinCreateMsgQueue 

• WinDispatchMsg 

• WinGetDIgMsg 

• WinGetMsg 

• WinlnSendMsg 

• WinPeekMsg 

• WinPostMsg 

• WinPostQueueMsg 

• WinQueryMsgPos 

• WinQueryMsgTime 

• WinQueryQueuelnfo 

• WinQueryQueueStatus 

• WinRegisterllserDatatype 

• WinRegisterUserMsg 

• WinSendDIgltemMsg 

• WinSendMsg 

• WinSetClassMsglnterest 

• WinSetMsglnterest 

• WinSetMsgMode 

• WinSetSynchroMode 

• WinWaitMsg 
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WinDestroyMsgQueue  - 
Destroy  Message  Queue 


Example  Code 

This  example  destroys,  using  WinDestroyMsgQueue,  a message  queue  previously  created  by 
WinCreateMsgQueue. 


#define  INCL_WINMESSAGEMGR  /*  Window  Message  Functions  */ 
fdefine  INCL_WINWINDOWMGR  /*  Window  Manager  Functions  */ 
finclude  <os2.h> 


BOOL 

fDestroyed; 

/*  success  of  destroy  call 

*/ 

HAB 

hab; 

/*  anchor-block  handle 

*/ 

HMQ 

hmq; 

/*  message  queue  handle 

*/ 

hab  = Winlnitialize(O);  /*  initialize  PM  */ 

hmq  = WinCreateMsgQueue(hab,  0);  /*  create  default  size  queue  */ 

/* 

. initialize  windows,  message  loop 
*/ 

fDestroyed  = WinDestroyMsgQueue(hmq) ; 
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WinDestroyObject  - 
Destroy  Workplace  Object 


#define  INCL_WINWORKPLACE 


BOOL  WinDestroyObject  (HOBJECT  object) 


The  WinDestroyObject  function  is  called  to  delete  a workplace  object. 

Parameters 

object  (HOBJECT)  - input 

Handle  to  a workplace  object. 


Returns 

Success  indicator. 

TRUE  Successful  completion. 

FALSE  Error  occurred. 

Remarks 

The  WinDestroyObject  function  will  permanently  remove  an  object  that  was  created  with  the 
WinCreateObject  function. 

Related  Functions 

• WinCreateObject 

• WinSetObjectData 


8-106  PM  Programming  Reference 


WinDestroyPointer  - 
Destroy  Pointer 


#define  INCL.WINPOINTERS  /*  Or  use  INCL_WIN  or  INCL_PM  7 


BOOL  WinDestroyPointer  (HPOINTER  hptrPoInter) 


This  function  destroys  a pointer  or  icon. 


Parameters 

hptrPoInter  (HPOINTER)  - input 

Handle  of  pointer  to  be  destroyed. 


Returns 

Success  indicator: 

TRUE  Successful  completion 
FALSE  Error  occurred. 

Possible  returns  from  WinGetLastError 

PMERR  INVALID  HPTR  An  invalid  pointer  handle  was  specified. 

Remarks 

A pointer  can  only  be  destroyed  by  the  thread  that  created  it. 

The  system  pointers  and  icons  must  not  be  destroyed. 


Related  Functions 

• WinCreatePointer 

• WinCreatePointerlndirect 

• WinDrawPointer 

• WinLoadPointer 

• WinQueryPointer 

• WinQueryPointerlnfo 

• WinQueryPointerPos 

• WinQuerySysPointer 

• WinSetPointer 

• WinSetPointerPos 

• WinShowPointer 
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Win  Destroy  Pointer 
Destroy  Pointer 


Example  Code 

This  example  destroys  a bit-map  pointer,  created  by  either  WinCreatePointer  or 
WinCreatePointerlndirect,  once  the  window  has  received  a close  message  (WM  CLOSE). 


Idefine  INCLJIINPOINTERS  /*  Window  Pointer  Functions  */ 
Idefine  I NC L_G P I B I TM APS  /*  Graphics  Bit-map  Functions  */ 
#include  <os2.h> 

Idefine  IDP_BITMAP  1 

HPS  hps;  /*  presentation-space  handle  */ 
HWND  hwnd;  /*  window  handle  */ 
HPOINTER  hptr;  /*  bit-map  pointer  handle  */ 
HBITMAP  hbm;  /*  bit-map  handle  */ 
BOOL  f Success;  /*  success  indicator  */ 


case  WM_CREATE: 

hps  = WinBeginPaint(hwnd,  NULLHANDLE,  NULL); 

hbm  = Gpi LoadBitmap(hps,  0L,  IDP_BITMAP,  64L,  64L); 

WinEndPaint(hps) ; 

hptr  = WinCreatePointer(HWND_DESKTOP,  hbm, 

TRUE,  /*  use  true  (system)  pointer  */ 
0,  0);  /*  hot  spot  offset  (0,0)  */ 


case  WM_CL0SE: 

fSuccess  = WinOestroyPointer(hptr) ; 
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Win  Destroy  Window  - 
Destroy  Window 


#define  INCL_WINWINDOWMGR  /*  Or  use  INCL_WIN  or  INCL_PM.  Also  in  COMMON  section  7 


BOOL  WinDestroy Window  (HWND  hwnd) 


This  call  destroys  a window  and  its  child  windows. 

Parameters 

hwnd  (HWND)  - input 
Window  handle. 


Returns 

Window-destroyed  indicator: 

TRUE  Window  destroyed 
FALSE  Window  not  destroyed. 

Possible  returns  from  WinGetLastError 

PMERR  INVALID  HWND  An  invalid  window  handle  was  specified. 

Remarks 

The  window  to  be  destroyed  must  have  been  created  by  the  thread  that  is  issuing  this  call.  Before 
hwnd  is  itself  destroyed,  all  windows  owned  by  hwnd  are  also  destroyed. 

If  hwnd  cannot  be  destroyed,  for  example  because  hwnd  is  an  invalid  window  handle  or  is  not 
associated  with  the  current  thread,  fSuccess  returns  FALSE. 

Note:  If  hwnd  is  locked,  this  call  does  not  return  until  the  window  is  unlocked  (and  destroyed). 

Messages  may  be  received  from  other  processes  or  threads  during  the  processing  of  this  call. 

If  a Presentation  Space  is  associated  with  the  window,  it  is  disassociated  from  it  by  this  function.  If 
the  presentation  space  was  obtained  by  use  of  the  GpiCreatePS  function,  then  it  is  disassociated 
from  the  window,  but  not  destroyed.  That  is,  this  function  performs  the  GpiAssociate  function  to 
disassociate  the  presentation  space  but  does  not  perform  the  GpiDestroyPS  function.  If  the 
presentation  space  was  obtained  by  use  of  the  WinGetPS  function,  it  is  released  by  this  function;  that 
is,  this  function  performs  the  WinReleasePS  function. 

Messages  sent  by  this  call  are: 

WM  DESTROY  Always  sent  to  the  window  being  destroyed  after  the  window  has 

been  hidden  on  the  device,  but  before  its  child  windows  have  been 
destroyed.  The  message  is  sent  first  to  the  window  being 
destroyed,  then  to  the  child  windows  as  they  are  destroyed. 
Therefore,  during  processing  the  WM_DESTROY  it  can  be 
assumed  that  all  the  children  still  exist. 

WM_ACTIVATE  Sent  with  usactive  set  to  FALSE  if  the  window  being  destroyed  is 

the  active  window. 

WM_RENDERALLFMTS  Sent  if  the  clipboard  owner  is  being  destroyed,  and  there  are 

unrendered  formats  in  the  clipboard. 
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Destroy  Window 


If  the  window  being  destroyed  is  the  active  window,  both  the  active  window  and  the  input  focus 
window  are  transferred  to  another  window  when  the  window  is  destroyed.  The  window  that  becomes 
the  active  window  is  the  next  window,  as  defined  for  the  ‘Alt+Esc’  function.  This  usually  corresponds 
to  the  next  application  in  the  sequence.  The  input  focus  transfers  to  whichever  window  the  new 
active  window  decides  should  have  it. 

If  a menu  window  is  being  destroyed,  any  bit  maps  associated  with  the  menu  are  not  deleted.  They 
will  be  deleted  automatically  when  the  application  terminates. 


Related  Functions 

• WinCalcFrameRect 

• WinCreateFrameControls 

• WinCreateStdWindow 

• WinCreateWindow 

• WinDefWindowProc 

• WinQueryClassinfo 

• WinQueryClassName 

• WinRegisterClass 

• WinSubclassWindow 

Related  Messages 

• WM_  ACTIVATE 

• WM_DESTROY 

• WM_RENDERALLFMTS 

Example  Code 

This  example  destroys  the  specified  window  and  all  other  windows  owned  by  that  window  in 
response  to  a WM_CLOSE  message. 

fdefine  INCL_WINWINDOWMGR  /*  Window  Manager  Functions  */ 

linclude  <os2.h> 

ULONG  f Success; 

HWND  hwnd;  /*  cursor  display  window  */ 

case  WM_CL0SE: 

fSuccess  = WinDestroyWindow (hwnd) ; 
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WinDismissDIg  - 
Dismiss  Dialog 


#define  INCL_WINDIALOGS  /*  Or  use  INCL_WIN  or  INCL_PM.  Also  in  COMMON  section  */ 


BOOL  WinDismissDIg  (HWND  hwndDIg,  ULONG  ulResult) 


This  function  hides  the  modeless  dialog  window,  or  destroys  the  modal  dialog  window,  and  causes 
the  WinProcessDIg  or  WinDIgBox  functions  to  return. 


Parameters 

hwndDIg  (HWND)  - input 
Dialog-window  handle. 

ulResult  (ULONG)  - input 
Reply  value. 

Returned  to  the  caller  of  the  WinProcessDIg  or  WinDIgBox  functions. 


Returns 

Dialog-dismissed  indicator: 

TRUE  Dialog  successfully  dismissed 

FALSE  Dialog  not  successfully  dismissed. 

Possible  returns  from  WinGetLastError 

PMERR  INVALID  HWND  An  invalid  window  handle  was  specified. 

Remarks 

This  function  is  required  to  complete  the  processing  of  a modal  dialog  window  and  is  called  from  its 
dialog  procedure.  It  is  made  implicitly  if  the  dialog  procedure  passes  a WM  COMMAND  message  to 
WinDefDIgProc  or  if  a WM_QUIT  message  is  encountered  during  a WinProcessDIg  or  WinGetDIgMsg 
function. 

This  function  hides  the  dialog  window,  and  re-enables  any  windows  that  were  disabled  by  a 
WinProcessDIg  or  WinGetDIgMsg  function. 

It  does  not  destroy  the  dialog  window;  a WinDestroyWindow  function  must  be  issued  to  destroy  the 
dialog  window  when  it  is  no  longer  needed.  However,  the  WinDIgBox  function  destroys  the  dialog 
window  it  creates,  when  the  dialog  window  is  dismissed  by  the  use  of  this  function. 

This  function  can  be  issued  during  the  processing  of  the  the  WM  JNITDLG  (Default  Dialogs)  message. 

Note:  This  function  can  be  made  from  a modeless  dialog  window,  although  this  is  not  necessary  as 
there  is  no  internal  message  processing  loop.  If  it  is  called,  the  dialog  window  is  hidden  and 
it  is  the  responsibility  of  the  application  to  destroy  the  dialog  window,  if  required. 


Related  Functions 

• WinCreateDIg 

• WinDefDIgProc 

• WinDIgBox 

• WinGetDIgMsg 

• WinLoadDIg 

• WinProcessDIg 
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WinDismissDIg 
Dismiss  Dialog 


Related  Messages 

• WM_COMMAND 

• WM_QUIT 

• WMJNITDLG  (Default  Dialogs) 

Example  Code 

This  example  shows  a typical  dialog  procedure  that  has  both  an  OK  and  a Cancel  button.  If  the  user 
selects  the  OK  button,  WinDismissDIg  is  called  with  a result  value  of  TRUE.  If  the  user  selects  the 
Cancel  button,  WinDismissDIg  is  called  with  a result  value  of  TRUE. 

Idefine  INCL_WINDIALOGS  /*  Window  Dialog  Mgr  Functions  */ 

linclude  <os2.h> 

Idefine  ID_ENTER  101; 

Idefine  ID_CANCEL  102; 

MPARAM  mpl; 

HWND  hwnd; 

case  WM_COMMAND : 

switch  (SHORTlFROMMP(mpl))  { 

case  ID_ENTER:  /*  OK  button  selected  */ 

WinDismissDlg(hwnd,  TRUE); 
return  (0L) ; 

case  ID_CANCEL:  /*  Cancel  button  selected  */ 

WinDismissDlg(hwnd,  FALSE); 
return  (0L); 
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WinDispatchMsg  - 
Dispatch  Message 


#define  INCL_WINMESSAGEMGR  /*  Or  use  INCL_WIN  or  INCL_PM.  Also  in  COMMON  section  */ 


M RESULT  WinDispatchMsg  (HAB  hab,  PQMSG  pqmsgMsg) 


This  function  invokes  a window  procedure. 


Parameters 

hab  (HAB)  - input 

Anchor-block  handle. 


pqmsgMsg  (PQMSG)  - input 
Message  structure. 


Returns 

Message-return  data. 


Remarks 

This  function  is  equivalent  to  using  the  WinSendMsg  function  with  the  parameters  corresponding  to 
those  in  pqmsgMsg. 

The  time  and  pointer  position  information  within  pqmsgMsg  can  be  obtained  by  the  window 
procedure  with  the  WinQueryMsgTime  and  WinQueryMsgPos  functions. 

mresReply  is  the  value  returned  by  the  invoked  window  procedure.  For  standard  window  classes, 
the  values  of  mresReply  are  documented  with  the  message  definitions;  see  Chapter  11, 
“Introduction  to  Message  Processing”  on  page  11-1. 


Related  Functions 

• WinCancelShutdown 

• WinBroadcastMsg 

• WinCreateMsgQueue 

• WinDestroyMsgQueue 

• WinGetDIgMsg 

• WinGetMsg 

• WinlnSendMsg 

• WinPeekMsg 

• WinPostMsg 

• WinPostQueueMsg 

• WinQueryMsgPos 

• WinQueryMsgTime 

• WinQueryQueuelnfo 

• WinQueryQueueStatus 

• WinRegisterUserDatatype 

• WinRegisterUserMsg 

• WinSendDIgltemMsg 

• WinSendMsg 

• WinSetClassMsglnterest 

• WinSetMsglnterest 

• WinSetMsgMode 

• WinSetSynchroMode 

• WinWaitMsg 
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WinDispatchMsg 
Dispatch  Message 


Example  Code 

This  example,  after  uses  WinDispatchMsg  within  a WinGetMsg  loop  to  dispatch  window  messages  to 
a window  procedure. 


fdefine  INCL_WINMESSAGEMGR  /*  Window  Message  Functions  */ 
fdefine  INCL_WINWINDOWMGR  /*  Window  Manager  Functions  */ 
finclude  <os2.h> 

HAB  hab;  /*  anchor-block  handle  */ 
HMQ  hmq;  /*  message  queue  handle  */ 
QMSG  qmsg;  /*  message  */ 


hab  = Winlnitialize(O);  /*  initialize  PM  */ 

hmq  = WinCreateMsgQueue(hab,  0);  /*  create  default  size  queue  */ 

/* 

. initialize  windows 


*/ 

/*  get  and  dispatch  messages  from  queue  */ 
while  (WinGetMsg (hab,  &qmsg,  0,  0,  0)) 
WinDispatchMsg (hab,  &qmsg); 
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WinDIgBox  - 

Load  and  Process  Modal  Dialog 


#define  INCL_WINDIALOGS  /*  Or  use  INCL_WIN  or  INCL_PM.  Also  in  COMMON  section  7 


ULONG  WinDIgBox  (HWND  hwndParent,  HWND  hwndOwner,  PFNWP  pDIgProc, 

HMODULE  Resource,  ULONG  uIDIgld,  PVOID  pCreateParams) 


This  function  loads  and  processes  a modal  dialog  window  and  returns  the  result  value  established  by 
the  WinDismissDIg  call. 

Parameters 

hwndParent  (HWND)  - input 

Parent-window  handle  of  the  created  dialog  window: 

HWND_DESKTOP  The  desktop  window 

HWND_OBJECT  Object  window 

Other  Specified  window. 

hwndOwner  (HWND)  - input 

Requested  owner-window  handle  of  the  created  dialog  window. 

The  actual  owner  window  is  calculated  using  the  algorithm  specified  in  the  description  of  the 
WinLoadDIg  function. 

pDIgProc  (PFNWP)  - input 

Dialog  procedure  for  the  created  dialog  window. 

Resource  (HMODULE)  - input 

Resource  identity  containing  the  dialog  template. 

NULLHANDLE  Use  the  application’s  .EXE  file. 

Other  Module  handle  returned  from  the  DosLoadModule  or  DosGetModHandle  call. 

uIDIgld  (ULONG)  - input 

Dialog-template  identity  within  the  resource  file. 

It  is  also  used  as  the  identity  of  the  created  dialog  window. 

pCreateParams  (PVOID)  - input 
Application-defined  data  area. 

This  is  passed  to  the  dialog  procedure  in  the  WMJNITDLG  message. 


Returns 

Reply  value. 

Value  established  by  the  WinDismissDIg  call  or  DID_ERROR  if  an  error  occurs. 


Possible  returns  from  WinGetLastError 

PMERRINVALIDHWND 
PMERRJNVALIDJNTEGERATOM 
PMERRINVALIDATOMNAME 
P M E RRATOMN  AM  E_NOT_FOU  N D 
PMERRRESOURCENOTFOUND 


An  invalid  window  handle  was  specified. 

The  specified  atom  is  not  a valid  integer  atom. 

An  invalid  atom  name  string  was  passed. 

The  specified  atom  name  is  not  in  the  atom  table. 
The  specified  resource  identity  could  not  be  found. 
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Load  and  Process  Modal  Dialog 


Remarks 

The  use  of  parameters  to  this  function  are  the  same  as  those  of  the  WinLoadDIg  function. 

This  function  should  not  be  used  while  pointing  device  capture  is  set  (see  “WinSetCapture  - Set 
Capture”  on  page  8-442). 

This  function  does  not  return  until  WinDismissDIg  is  called. 

This  function  is  equivalent  to: 

WinLoadDIg  (.,  •>  dig); 

WinProcessDlg  (dig,  result); 

WinDestroyWindow  (dig,  success); 
return  (result); 

and  the  remarks  documented  under  these  calls  also  apply. 

If  a dialog  template  (typically  compiled  using  the  resource  compiler)  references  another  resource 
(for  example  an  icon  resource  for  an  icon  static  control),  this  function  always  searches  for  that 
resource  in  the  .EXE  file.  If  an  application  wishes  to  keep  resources  referenced  by  a dialog  template 
in  a .DLL  library,  these  resources  must  be  loaded  by  an  explicit  function  call  during  the  processing  of 
the  WM JNITDLG  message. 

Note:  This  can  be  considered  to  be  a customizable  “read  from  screen”  call.  The  caller  supplies  a 
data  buffer  (th e pCreateParams  parameter),  filled  with  initial  values.  It  receives  a return  code 
which  indicates  whether  the  data  in  the  buffer  has  been  updated  and  validated,  or  whether  the 
end  user  cancelled  the  dialog. 

The  end  user  interface  is  encapsulated  within  the  dialog  window.  The  dialog  template 
provides  a view  of  the  current  state  of  the  data  buffer,  the  dialog  procedure  defines  how  the 
user  can  change  the  data. 

The  caller  need  know  nothing  about  the  details  of  the  end  user  interface.  It  makes  a single 
“ read  from  screen"  call  and  continues  with  its  work. 

Related  Functions 

• WinCreateDIg 

• WinDefDIgProc 

• WinDismissDIg 

• WinGetDIgMsg 

• WinLoadDIg 

• WinProcessDlg 

Related  Messages 

• WMJNITDLG 
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Load  and  Process  Modal  Dialog 


Example  Code 

This  example  processes  an  application-defined  message  (IDM_OPEN)  and  calls  WinDIgBox  to  load  a 
dialog  box. 

Idefine  IDD_0PEN  1 

Idefine  INCL_WINDIALOGS  /*  Window  Dialog  Mgr  Functions  */ 

linclude  <os2.h> 


HWND  hwndFrame;  /*  frame  window  handle  */ 

PFNWP  OpenDlg; 

case  I DM  OPEN: 

if  (WinDlgBox(HWND_DESKTOP, 

hwndFrame,  /*  handle  of  the  owner  */ 

OpenDlg,  /*  dialog  procedure  address  */ 

NULLHANDLE,  /*  location  of  dialog  resource  */ 

IDD_0PEN,  /*  resource  identifier  */ 

NULL))  { /*  application-specific  data  */ 


. /*  code  executed  if  dialog  box  returns  TRUE  */ 

} 
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WinDrawBitmap 
Draw  Bit  Map 


#define  INCL_WINWINDOWMGR  /*  Or  use  INCL_WIN  or  INCL_PM  */ 


BOOL  WinDrawBitmap  (HPS  hps,  HBITMAP  hbm,  PRECTL  prcISrc,  PPOINTL  pptIDest, 
LONG  IForeColor,  LONG  IBackColor,  ULONG  fIRgf) 


This  function  draws  a bit  map  using  the  current  image  colors  and  mixes. 

Parameters 

hps  (HPS)  - input 

Handle  of  presentation  space  in  which  the  bit  map  is  drawn. 

hbm  (HBITMAP)  - input 
Bit-map  handle. 

prcISrc  (PRECTL)  - input 

Subrectangle  of  bit  map  to  be  drawn: 

Note:  The  value  of  each  field  in  this  structure  must  be  in  the  range  -32  768  through  32  767.  The 
datatype  WRECT  can  also  be  used,  if  supported  by  the  language. 

NULL  The  whole  of  the  bit  map  is  drawn 

Other  The  whole  of  the  bit  map  is  not  drawn. 

pptIDest  (PPOINTL)  - input 
Bit-map  destination. 

The  bottom  left  corner  of  the  bit-map  destination  is  specified  in  device  coordinates. 

IForeColor  (LONG)  - input 
Foreground  color. 

This  is  used  if  hbm  refers  to  a monochrome  bit  map.  In  this  instance,  bit-map  bits  that  are  set  to 
1 are  drawn  using  IForeColor.  Ignored  if  DBMJMAGEATTRS  is  specified. 

IBackColor  (LONG)  - input 
Background  color. 

This  is  used  if  hbm  refers  to  a monochrome  bit  map.  In  this  instance,  bit-map  bits  that  are  set  to 
zero  are  drawn  using  IBackColor.  Ignored  if  DBMJMAGEATTRS  is  specified. 

fIRgf  (ULONG)  - input 

Flags  that  determine  how  the  bit  map  is  drawn: 

DBM_NORMAL  Draw  the  bit  map  normally  using  ROP_SRCCOPY,  as  defined  in  GpiBitBIt. 

DBM  INVERT  Draw  the  bit  map  inverted  using  ROP_NOTSRCCOPY,  as  defined  in 

GpiBitBIt. 

DBM_STRETCH  pptIDest  points  to  a RECT  data  structure,  representing  a rectangle  in  the 
destination  presentation  space,  to  which  the  bit  map  should  be  stretched 
or  compressed.  If  compression  is  required,  some  rows  and  columns  of 
the  bit  map  are  eliminated. 

DBM_HALFTONE  Use  the  OR  operator  to  combine  the  bit  map  with  an  alternating  pattern  of 
ones  or  zeros  before  drawing  it.  It  can  be  used  with  either  DBMJMORMAL 
or  DBMJNVERT. 

DBMJMAGEATTRS  If  this  is  specified,  color  conversion  of  monochrome  bit  maps  is  done  by 
using  the  image  attributes. 
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Draw  Bit  Map 


Returns 

Success  indicator: 

TRUE  Successful  completion 
FALSE  Error  occurred. 

Possible  returns  from  WinGetLastError 

An  invalid  bit  was  set  for  a parameter.  Use  constants 
defined  by  PM  for  options,  and  do  not  set  any  reserved 
bits. 

An  internal  bit  map  busy  error  was  detected.  The  bit  map 
was  locked  by  one  thread  during  an  attempt  to  access  it 
from  another  thread. 


PMERR_INVALID_FLAG 

PMERRHBITMAPBUSY 


Remarks 

This  function  should  only  be  used  in  draw  mode  (DM_DRAW)  to  a screen  device  context  (see 
GpiSetDrawingMode).  The  presentation  space  handle  can  be  to  either  a micro-presentation  space  or 
a normal  presentation  space  (see  GpiCreatePS). 

If  hbm  refers  to  a color  bit  map,  no  color  conversion  is  performed. 

The  current  position  in  the  presentation  space  is  not  changed  by  this  function. 


Related  Functions 

• WinDrawBorder 

• WinDrawPointer 

• WinDrawText 

• WinFillRect 

• WinGetSysBitmap 

• WinlnvertRect 

• WinQueryPresParam 

• WinRemovePresParam 

• WinScrollWindow 

• WinSetPresParam 
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WinDrawBitmap 
Draw  Bit  Map 


Example  Code 

This  example  uses  WinDrawBitmap  to  draw  the  system-defined  menu  check  mark  bit  map  in 
response  to  the  user  selecting  a menu  item  (WM_MENUSELECT),  using  the  bit-map  handle  returned 
by  WinGetSysBitmap. 


Idefine  INCL_WINWINDOWMGR 
Idefine  INCL_WINPOINTERS 
Idefine  I NCL_WI NMESSAGEMGR 
Idefine  INCL_WINMENUS 
linclude  <os2.h> 


/*  Window  Manager  Functions  */ 
/*  Window  Pointer  Functions  */ 
/*  Window  Message  Functions  */ 
/*  Window  Menu  Functions  */ 


HPS  hps;  / 
H BITMAP  hbmCheck;  / 
HWND  hwndMenu;  / 
USHORT  usltemld;  / 
RECTL  rclltem;  / 
MPARAM  mpl;  / 
MPARAM  mp2;  / 


presentation-space  handle 
check  mark  bit-map  handle 
menu  handle 
menu  item  id 
item  border  rectangle 
Parameter  1 (menu  item  id) 
Parameter  2 (menu  handle) 


*/ 

*/ 

*/ 

*/ 

*/ 

*/ 

*/ 


case  WM_CREATE: 

/*  obtain  check  mark  bit-map  handle  */ 

hbmCheck  = WinGetSysBitmap(HWND_DESKTOP,  SBMP_MENUCHECK) ; 


case  WM  MENUSELECT: 

usltemld  = SHORTlFROMMP(mpl) ; 
hwndMenu  = HWNDFR0MMP(mp2) ; 


/*  get  rectangle  of  selected  item  */ 

Wi nSendMs  g ( hwndMenu , 

MM_QUERYITEMRECT, 

MPFR0M2SH0RT ( us I temld , TRUE), 
MPFROMP(&rc litem)); 


/*  draw  the  check  mark  in  the  lower  left  corner  of  item's 
rectangle  */ 
if  (hbmCheck  !=  NULL) 

{ 

WinDrawBitmap(hps, 

hbmCheck,  /*  check  mark  */ 

NULL,  /*  draw  whole  bit  map  */ 

(PPOINTL)&rcl Item,/*  bit-map  destination  */ 
0L,  /*  ignored  since  color  */ 

OL,  /*  bit  map  */ 

DBM_NORMAL);  /*  draw  normal  size  */ 
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WinDrawBorder  - 
Draw  Border 


#define  INCL_WINWINDOWMGR  /*  Or  use  INCL_WIN  or  INCL_PM  */ 


BOOL  WinDrawBorder  (HPS  hps,  PRECTL  prcIRectangle,  LONG  IVertSIdeWldth, 

LONG  IHorlzSIdeWldth,  LONG  IBorderColor,  LONG  IlnterlorColor, 
ULONG  fICmd) 


This  function  draws  the  borders  and  interior  of  a rectangle. 


Parameters 

hps  (HPS)  - input 

Presentation-space  handle. 

prcIRectangle  (PRECTL)  - input 

Bounding  rectangle  for  the  border. 

The  rectangle  is  in  device  coordinates. 

The  border  is  drawn  within  the  rectangle.  Along  the  bottom  and  left  edges  of  the  rectangle,  the 
edges  of  the  border  coincide  with  the  rectangle  edges.  Along  the  top  and  right  edges  of  the 
rectangle,  the  border  is  drawn  one  device  unit  inside  the  rectangle  edges. 

Note:  The  value  of  each  field  in  this  structure  must  be  in  the  range  —32  768  through  32  767.  The 
data  type  WRECT  can  also  be  used,  if  supported  by  the  language. 

IVertSIdeWldth  (LONG)  - input 

Width  of  border  rectangle  vertical  sides. 

This  is  the  width  of  the  left  and  right  sides  in  device  coordinates. 

IHorlzSIdeWldth  (LONG)  - input 

Width  of  border  rectangle  horizontal  sides. 

This  is  the  width  of  the  top  and  bottom  sides  in  device  coordinates. 

IBorderColor  (LONG)  - input 
Color  of  edge  of  border. 

Not  used  if  DB_AREAATTRS  is  specified. 

IlnterlorColor  (LONG)  - input 
Color  of  interior  of  border. 

Not  used  if  DB_AREAATTRS  is  specified. 

fICmd  (ULONG)  - input 

Flags  controlling  the  way  in  which  the  border  is  drawn. 

Some  of  the  DB_  flags  are  mutually  exclusive.  Only  one  of  these  four  can  be  significant: 

• DB_PATCOPY  (default) 

• DB_PATINVERT 

• DB_DESTINVERT 

• DB_AREAMIXMODE. 

DBROP 

A group  of  flags  that  specify  the  mix  to  be  used,  for  both  the  border  and  the  interior. 

DB_PATCOPY 

Use  the  ROP_PATCOPY  raster  operation  (see  GpiBitBIt).  This  is  a copy  of  the  pattern  to  the 
destination. 
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Draw  Border 


DB_PATINVERT 

Use  the  ROP_PATINVERT  raster  operation  (see  GpiBitBIt).  This  is  an  exclusive-OR  of  the 
pattern  with  the  destination. 

DB_DESTINVERT 

Use  the  ROP_DESTINVERT  raster  operation  (see  GpiBitBIt).  This  inverts  the  destination. 

DB_  AREAMIXMODE 

Map  the  current  area  foreground  mix  attribute  into  a Bitblt  raster  operation  (see  GpiBitBIt). 
The  area  background  mix  mode  is  ignored. 

DBJNTERIOR 

The  area  contained  within  the  given  rectangle,  and  not  included  within  the  borders  (as  given 
by  IVertSideWidth  and  IHorizSideWidth),  is  drawn. 

DB_AREAATTRS 

• If  this  is  specified: 

For  any  border,  the  pattern  used  is  the  pattern  as  currently  defined  in  the  area  attribute. 

For  any  interior,  the  pattern  used  is  the  same  as  if  a GpiSetAttrs  function  for  the  area 
attributes  is  made  with  the  background  color  of  the  area  attribute  being  passed  for  the 
foreground  color,  and  the  foreground  color  of  the  area  attribute  being  passed  as  the 
background  color. 

• If  this  is  not  specified  (default): 

For  any  border,  the  pattern  used  is  the  same  as  if  a GpiSetAttrs  function  for  the  area 
attributes  is  made  with  a foreground  color  of  IBorderColor,  and  a background  color  of 
IlnteriorColor. 

For  any  interior,  the  pattern  used  is  the  same  as  if  a GpiSetAttrs  function  for  the  area 
attributes  is  made  with  a foreground  color  of  IlnteriorColor,  and  a background  color  of 
IBorderColor. 

DB_STANDARD 

IVertSideWidth  and  IHorizSideWidth  are  multiplied  by  the  system  SV  CXBORDER  and 
SV_CYBORDER  constants  to  produce  the  widths  of  the  vertical  and  horizontal  sides  of  the 
border. 

DB_DLGBORDER 

A standard  dialog  border  is  drawn,  in  the  active  titlebar  color  if  DB_PATCOPY  is  specified,  or 
the  inactive  titlebar  color  if  DB_PATINVERT  is  specified.  Other  DB_ROP  options,  and 
DB_AREAATTRS,  are  ignored. 

DB_ROP  and  DB_AREAATTRS  are  also  ignored  for  the  interior.  The  interior  is  drawn  in  the 
color  specified  by  IlnteriorColor. 


Returns 

Success  indicator: 

TRUE  Successful  completion 
FALSE  Error  occurred. 


Possible  returns  from  WinGetLastError 

PMERRJNVALID  FLAG  An  invalid  bit  was  set  for  a parameter.  Use  constants 

defined  by  PM  for  options,  and  do  not  set  any  reserved 
bits. 

PMERR_INV_DRAW_BORDER_OPTION  An  invalid  option  parameter  was  specified  with 

WinDrawBorder. 
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WinDrawBorder  - 
Draw  Border 


Remarks 

A border  is  a rectangular  frame,  normally  used  around  the  edge  of  a window. 

This  function  should  only  be  used  in  draw  mode  (DMDRAW),  to  a screen  device  context;  hps  can  be 
either  a micro-presentation  space  or  a normal  presentation  space  (see  GpiCreatePS). 
DB_DESTINVERT  inverts  the  destination. 

If  DB_AREAMIXMODE  is  given,  the  foreground  mix  mode  from  the  area  attribute  is  mapped  into  an 
equivalent  ROP_  value  (see  GpiBitBIt).  The  area  background  mix  mode  is  ignored. 

Either  or  both  IVertSideWidth  or  IHorizSideWidth  can  be  zero.  If  both  are  zero,  the  interior  is  still 
drawn.  If  either  the  x borders  overlap  or  the  y borders  overlap,  the  border  is  drawn  as  a single 
rectangle  with  no  interior. 


Related  Functions 

• WinDrawBitmap 

• WinDrawPointer 

• WinDrawText 

• WinFillRect 

• WinGetSysBitmap 

• WinlnvertRect 

• WinQueryPresParam 

• WinRemovePresParam 

• WinScrollWindow 

• WinSetPresParam 

Example  Code 

This  example  uses  WinDrawBorder  to  draw  the  border  (width  of  5)  and  interior  of  a 300x200 
rectangle  anchored  at  (0,0),  and  using  the  area's  current  attributes  for  both  the  border  and  interior 
colors. 


Idefine  INCL_WINWIND0WMGR  /*  Window  Manager  Functions  */ 

linclude  <os2.h> 

HPS  hps;  /*  presentation-space  handle  */ 

BOOL  fSuccess;  /*  success  indicator  */ 

RECTL  prclRectangle={0, 0,300, 200};  /*  border  rectangle  */ 

LONG  lVertSideWidth=5;  /*  Width  of  border  rectangle  vertical 

sides  */ 

LONG  lHorizSideWidth=5;/*  Width  of  border  rectangle  horizontal 

sides  */ 

UL0NG  flCmd;  /*  draw  flags  */ 


/*  use  current  area  attributes  */ 
flCmd  = DB_AREAATTRS ; 

fSuccess  = WinDrawBorder(hps,  &prcl Rectangle,  IVertSideWidth, 

IHorizSideWidth,  0L,  0L,  flCmd); 
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WinDrawPointer 
Draw  Pointer 


#define  INCL_WINPOINTERS  /*  Or  use  INCL_WIN  or  INCL_PM  7 


BOOL  WinDrawPointer  (HPS  hps,  LONG  lx,  LONG  ly,  HPOINTER  hptrPoInter, 
ULONG  ulHalftone) 


This  function  draws  a pointer  in  the  passed  hps  at  the  passed  coordinates  [/x,  /y]. 

Parameters 

hps  (HPS)  - input 

Presentation-space  handle  into  which  the  pointer  is  drawn. 

This  can  be  either  a micro  presentation  space  or  a normal  presentation  space  (see 
GpiCreatePS). 

lx  (LONG)  - input 

x coordinate  at  which  to  draw  the  pointer,  in  device  coordinates, 
ly  (LONG)  - input 

y coordinate  at  which  to  draw  the  pointer,  in  device  coordinates. 

hptrPoInter  (HPOINTER)  - input 
Pointer  handle. 

This  is  equivalent  to  a bit-map  handle  and  is  returned  from  calls  such  as  the  GpiLoadBitmap 
function. 

ulHalftone  (ULONG)  - input 

Shading  control  with  which  to  draw  the  pointer: 

DP_NORMAL  As  it  normally  appears. 

DP_HALFTONED  With  a halftone  pattern  where  black  normally  appears. 

DPJNVERTED  Inverted,  black  for  white  and  white  for  black. 

Returns 

Success  indicator: 

TRUE  Successful  completion 
FALSE  Function  failed. 

Possible  returns  from  WinGetLastError 

PMERR  INVALID  HPTR  An  invalid  pointer  handle  was  specified. 

PMERR_INVALID_FLAG  An  invalid  bit  was  set  for  a parameter.  Use  constants 

defined  by  PM  for  options,  and  do  not  set  any  reserved 
bits. 

Remarks 

This  function  should  only  be  used  in  draw  mode  (DM_DRAW)  to  a screen  device  context. 
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Draw  Pointer 


Related  Functions 

• WinDrawBitmap 

• WinDrawBorder 

• WinDrawText 

• WinFillRect 

• WinGetSysBitmap 

• WinlnvertRect 

• WinQueryPresParam 

• WinRemovePresParam 

• WinScrollWindow 

• WinSetPresParam 

• WinCreatePointer 

• WinCreatePointerlndirect 

• WinDestroyPointer 

• WinLoadPointer 

• WinQueryPointer 

• WinQueryPointerlnfo 

• WinQueryPointerPos 

• WinQuerySysPointer 

• WinSetPointer 

• WinSetPointerPos 

• WinShowPointer 


Example  Code 

This  example  draw  a bit  map  pointer,  created  by  either  WinCreatePointer  or 
WinCreatePointerlndirect,  in  response  to  a paint  message  (WM_PAINT). 


Idefine  INCL_WINPOINTERS  /*  Window  Pointer  Functions  */ 
Idefine  INCL_GPIBITMAPS  /*  Graphics  bit-map  functions  */ 
linclude  <os2.h> 

HPS  hps;  /*  presentation-space  handle  */ 
HWNO  hwnd;  /*  window  handle  */ 
HPOINTER  hptr;  /*  bit-map  pointer  handle  */ 
HBITMAP  hbm;  /*  bit-map  handle  */ 
BOOL  fSuccess;  /*  success  indicator  */ 
ULONG  ulHalftone=DP_NORMAL;  /*  draw  with  normal  shading  */ 


case  WM_CREATE: 

hps  = Wi nBegi nPa i nt ( hwnd , NULLHANDLE,  NULL); 
hbm  = GpiLoadBitmap(hps,  OL,  IDP_BITMAP,  64L,  64L); 
WinEndPaint(hps) ; 

hptr  = WinCreatePointer(HWND_DESKTOP,  hbm, 

TRUE,  /*  use  true  (system)  pointer  */ 
0,  0);  /*  hot  spot  offset  (0,0)  */ 

case  WM_PAINT : 

hps  = WinBeginPaint(hwnd,  NULLHANDLE,  NULL); 

fSuccess  = WinDrawPointer (hps,  50,  50,  hptr,  ulHalftone); 

WinEndPaint(hps) ; 
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WinDrawText 
Draw  Text 


#define  INCL_WINWINDOWMGR  /*  Or  use  INCL_WIN  or  INCL_PM  */ 


LONG  WinDrawText  (HPS  hps,  LONG  ICount,  PCH  pchText,  PRECTL  prcIRectangle, 
LONG  IForeColor,  LONG  IBackColor,  ULONG  fICmd) 


This  function  draws  a single  line  of  formatted  text  into  a specified  rectangle. 

Parameters 

hps  (HPS)  - input 

Presentation-space  handle. 

ICount  (LONG)  - input 

Count  of  the  number  of  characters  in  the  string: 

-1  The  string  is  null-terminated  and  its  length  is  to  be  calculated  by  this  function. 

Other  Count  of  the  number  of  characters  in  the  string. 

pchText  (PCH)  - input 

Character  string  to  be  drawn. 

A carriage-return  or  line-feed  character  terminates  the  line,  even  if  the  line  is  less  than  ICount. 

prcIRectangle  (PRECTL)  - input/output 
Text  rectangle. 

Rectangle  within  which  the  text  is  to  be  formatted,  in  world  coordinates.  Points  on  the  boundary 
of  this  rectangle  are  deemed  to  be  inside  the  rectangle. 

The  return  value  is  only  of  interest  in  the  instance  where  DT_QUERYEXTENT  is  set  in  fICmd. 

Note:  The  value  of  each  field  in  this  structure  must  be  in  the  range  —32  768  through  32  767.  The 
data  type  WRECT  can  also  be  used,  if  supported  by  the  language. 

IForeColor  (LONG)  - input 
Foreground  color. 

Ignored  if  DT_TEXT ATTRS  is  specified. 

IBackColor  (LONG)  - input 
Background  color. 

The  background  is  drawn  with  the  current  background  mix.  The  default  is  BM_LEAVEALONE, 
that  is,  IBackColor  is  ignored  unless  GpiSetBackMix  is  called. 

The  background  rectangle  is  the  rectangle  that  bounds  the  text;  it  is  not  the  input  parameter 
rectangle. 

This  parameter  is  ignored  if  DT_TEXT ATTRS  is  specified. 
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Draw  Text 


fICmd  (ULONG)  - input 

An  array  of  flags  that  determines  how  the  text  is  drawn. 

Some  of  the  DT_  flags  are  mutually  exclusive.  Only  one  from  each  of  these  groups  is  significant: 

• DT_LEFT  (default),  DT_CENTER,  DT_RIGHT 

• DT_TOP  (default),  DT.VCENTER,  DT_BOTTOM. 


When  mutually-exclusive  flags  are  used  together,  the  function  gives  indeterminate  results. 

If  DT_HALFTONE,  DT  ERASERECT,  or  DT_MNEMONIC  is  used,  the  presentation  space  must  be  in 
PU_PELS  units. 


DT_LEFT 

DT_CENTER 

DT_RIGHT 

DT_VCENTER 

DT_TOP 

DT_BOTTOM 

DT_HALFTONE 

DTMNEMONIC 

DT_QUERYEXTENT 

DTWORDBREAK 


Left-justify  the  text. 

Center  the  text. 

Right-justify  the  text. 

Vertically  center  the  text. 

Top-justify  the  text. 

Bottom-justify  the  text. 

Halftone  the  text  display. 

If  a mnemonic  prefix  character  is  encountered,  the  next  character  is 
drawn  with  mnemonic  emphasis. 

No  drawing  is  performed.  prcIRectangle  is  changed  to  a rectangle 
that  bounds  the  string  if  it  were  drawn  with  WinDrawText. 

Only  words  that  fit  completely  within  the  supplied  rectangle  are 
drawn.  A word  is  defined  as: 

Any  number  of  leading  spaces  followed  by  one  or  more  visible 
characters  and  terminated  by  a space,  carriage  return,  or  line-feed 
character. 


When  calculating  whether  a particular  word  fits  within  the  given 
rectangle,  this  function  does  not  consider  the  trailing  blanks.  Only 
the  length  of  the  visible  part  of  the  word  is  tested  against  the  right 
edge  of  the  rectangle. 

Also,  note  that  this  function  always  tries  to  draw  at  least  one  word, 
even  if  that  word  does  not  fit  in  the  passed  rectangle.  This  is  so  that 
progress  is  always  made  when  drawing  multiline  text. 


DT_EXTERNALLEADING  This  flag  causes  the  “external  leading”  value  for  the  current  font  to 

be  added  to  the  bottom  of  the  bounding  rectangle  before  returning.  It 
has  an  effect  only  when  both  DT_TOP  and  DT_QUERYEXTENT  are 
also  specified. 

DT_TEXTATTRS  If  this  is  specified,  text  is  drawn  using  the  character  foreground  and 

background  colors  of  the  presentation  space,  and  IForeColor  and 
IBackColor  are  ignored. 


DT_ERASERECT 


DTUNDERSCORE 

DT_STRIKEOUT 


If  this  is  specified,  the  rectangle  defined  by  prcIRectangle  is  erased 
before  drawing  the  text.  Otherwise,  the  background  of  the  characters 
themselves  can  be  erased  if  the  character  background  mix  (see 
GpiSetAttrs  and  GpiSetBackMix)  is  set  to  BM_OVERPAINT. 

Underscore  the  characters.  See  FATTR_SEL_UNDERSCORE  in  the 
FATTRS  datatype. 

Overstrike  the  characters.  See  FATTR_SEL_STRIKEOUT  in  the 
FATTRS  datatype. 
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Returns 

Count  of  characters  drawn  within  the  rectangle. 

If  DTWORDBREAK  is  specified,  this  parameter  returns  the  number  of  characters  displayed. 
However,  if  the  first  word  of  the  string  does  not  fit  in  the  rectangle,  this  parameter  reflects  the 
fact  that  the  entire  word  is  drawn. 

If  DT  WORDBREAK  is  not  specified,  the  count  returned  is  the  full  length  of  the  string  regardless 
of  how  much  fits  into  the  bounding  rectangle. 

0 Error  occurred 

Other  Count  of  characters  drawn  within  the  rectangle. 

Possible  returns  from  WinGetLastError 

PMERRJNVALID  FLAG  An  invalid  bit  was  set  for  a parameter.  Use  constants 

defined  by  PM  for  options,  and  do  not  set  any  reserved 
bits. 


Remarks 

Text  is  always  drawn  in  the  current  font  with  the  current  foreground  and  background  mix  modes. 

This  function  must  only  be  used  in  draw  mode  (DM_DRAW),  to  a screen  device  context;  hps  can  be 
either  a micro  presentation  space  or  a normal  presentation  space  (see  GpiCreatePS). 


Related  Functions 

• WinDrawBitmap 

• WinDrawBorder 

• WinDrawPointer 

• WinFillRect 

• WinGetSysBitmap 

• WinlnvertRect 

• WinQueryPresParam 

• WinRemovePresParam 

• WinScrollWindow 

• WinSetPresParam 
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Draw  Text 


Example  Code 

This  example  shows  how  the  WinDrawText  function  can  be  used  to  wrap  text  within  a window  by 
using  the  DTWORDBREAK  flag.  The  cchDrawn  variable  receives  the  number  of  characters  actually 
drawn  by  the  WinDrawText  function.  If  this  value  is  zero,  no  text  is  drawn  and  the  for  loop  is  exited. 
This  can  occur  if  the  vertical  height  of  the  window  is  too  short  for  the  entire  text.  Otherwise, 
cchDrawn  is  added  to  the  hTotalDrawn  variable  to  provide  an  offset  into  the  string  for  the  next  call  to 
WinDrawText. 


fdefine  INCL_WINWINDOWMGR  /*  Window  Manager  Functions  */ 

linclude  <os2.h> 


HWND 

hwnd; 

/*  parent  window 

RECTL 

rcl ; 

/*  update  region 

HPS 

hps; 

/*  presentation-space  handle 

char 

*pszText; 

/*  string 

LONG 

hText; 

/*  length  of  string 

LONG 

cyCharHeight; 

/*  set  character  height 

LONG 

hTotalDrawn; 

/*  total  characters  drawn 

LONG 

hDrawn; 

/*  characters  drawn  by  WinDrawText 

LONG 

cchText; 

LONG 

cchTotal Drawn; 

LONG 

cchDrawn; 

*/ 

*/ 

*/ 

*/ 

*/ 

*/ 

*/ 

*/ 


hps  = WinGetPS(hwnd) ; 


/*  get  a ps  for  the  entire  window  */ 


Wi nQueryWi ndowRect ( hwnd , &rcl ) ; 


/*  get  window  dimensions  */ 


WinFillRect(hps,  &rcl , CLR_WHITE) ; 


/*  clear  entire  window  */ 


cchText  = (LONG)strlen(pszText) ; /*  get  length  of  string  */ 

cyCharHeight  = 15L;  /*  set  character  height  */ 


/*  until  all  chars  drawn  */ 

for  (cchTotal Drawn  = 0;  hTotalDrawn  !=  hText; 

rcl .yTop  -=  cyCharHeight) 

{ 

/*  draw  the  text  */ 


hDrawn  = WinDrawText (hps, 
hText  - hTotalDrawn, 
pszText  + hTotalDrawn, 
&rcl , 

OL, 

OL, 

DT_WORDBREAK  | DT_T0P  | I 
if  (cchDrawn) 

hTotalDrawn  +=  hDrawn; 

else 

break; 

} 

WinReleasePS(hps) ; 


/*  presentation-space  handle  */ 


/*  length  of  text  to  draw  */ 

/*  address  of  the  text  */ 
/*  rectangle  to  draw  in  */ 

/*  foreground  color  */ 

/*  background  color  */ 

_LEFT  | DT_TEXTATTRS) ; 


/*  text  could  not  be  drawn  */ 
/*  release  the  ps  */ 
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Empty  Clipboard 


#define  INCL_WINCLIPBOARD  /*  Or  use  INCL_WIN  or  INCL_PM  7 


BOOL  WinEmptyClipbrd  (HAB  hab) 


This  function  empties  the  clipboard,  removing  and  freeing  all  handles  to  data  that  is  in  the  clipboard. 

Parameters 

hab  (HAB)  - input 

Anchor-block  handle. 


Returns 

Success  indicator: 

TRUE  Successful  completion 
FALSE  Error  occurred. 


Remarks 

The  clipboard  must  be  opened  using  WinOpenClipbrd  before  using  this  function. 

This  function  will  send  a WM_DESTROYCLIPBOARD  message  to  the  clipboard  owner. 


Related  Functions 

• WinCloseClipbrd 

• WinEnumClipbrdFmts 

• WinOpenClipbrd 

• WinQueryClipbrdOata 

• WinQueryClipbrdFmtlnfo 

• WinQueryClipbrdOwner 

• WinQueryClipbrdViewer 

• WinSetClipbrdData 

• WinSetClipbrdOwner 

• WinSetClipbrdViewer 

Example  Code 

This  example  empties  the  clipboard  (opened  by  WinOpenClipbrd),  removing  and  freeing  all  handles 
to  data  in  the  clipboard. 

fdefine  INCL_WINCLIPBOARD  /*  Window  Clipboard  Functions  */ 

linclude  <os2.h> 

BOOL  f Success;  /*  success  indicator  */ 

HAB  hab;  /*  anchor-block  handle  */ 


fSuccess  = WinOpenCl ipbrd(hab) ; 
if  (fSuccess) 

fSuccess  = WinEmptyClipbrd(hab); 
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Enable  Control  of  Button  Id 


#define  INCL_WINWINDOWMGR  /*  Or  use  INCL_WIN  or  INCL_PM  7 


BOOL  WinEnableControl  (HWND  hwndDIg,  USHORT  usld,  BOOL  fEnable) 


This  macro  sets  the  enable  state  of  the  item  in  the  dialog  template  to  the  enable  flag. 


Parameters 

hwndDIg  (HWND)  - input 
Dialog  window  handle. 

usld  (USHORT)  - input 

Identity  of  the  item  in  the  dialog  template  (button  id). 

fEnable  (BOOL)  - input 
Enable  flag. 


Returns 

Success  indicator: 

TRUE  Successful  completion 
FALSE  Error  occurred. 


Remarks 

This  macro  expands  to: 

Idefine  WinEnableControl (hwndDIg,  usld,  fEnable) 
WinEnableWindow(WinWindowFromId(hwndDlg,  usld),  fEnable) 

This  function  requires  the  existence  of  a message  queue. 


Related  Functions 

• WinEnableWindow 

• WinWindowFromID 

Example  Code 

This  example  uses  WinEnableControl  to  enable  a dialog  control  if  it  is  currently  disabled. 


Idefine  INCL_WINWINDOWMGR  /*  Window  Manager  Functions  */ 
linclude  <os2.h> 

HWND  hwndDIg;  /*  dialog  window  */ 
MPARAM  mpl;  /*  Parameter  1 */ 
USHORT  usld;  /*  dialog  control  id  */ 


if  (!WinIsControlEnabled(hwndDlg,  usld)) 
WinEnableControl (hwndDIg,  usld,  TRUE); 
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WinEnableMenultem 
Enable  Menu  Item 


#define  INCL_WINWINDOWMGR  /*  Or  use  INCL_WIN  or  INCL_PM  7 


BOOL  WinEnableMenultem  (HWND  hwndMenu,  USHORT  usld,  BOOL  (Enable) 


This  macro  sets  the  state  of  the  specified  menu  item  to  the  enable  flag. 


Parameters 

hwndMenu  (HWNO)  - input 
Menu  window  handle. 

usld  (USHORT)  - input 
Item  identifier. 

(Enable  (BOOL)  - input 
Enable  fiag. 


Returns 

Success  indicator: 

TRUE  Successful  completion 
FALSE  Error  occurred. 

Remarks 

This  macro  expands  to: 

fdefine  WinEnableMenuItem(hwndMenu,  usld,  fEnable) 

((BOOL)WinSendMsg(hwndMenu, 

MMSETITEMATTR, 

MPFR0M2SH0RT (usld,  TRUE), 

MPFR0M2SH0RT(MIA_DISABLED,  (BOOL) (fEnable)  ?0  : MIA_DISABLED))) 
This  function  requires  the  existence  of  a message  queue. 

Related  Functions 

• WinSendMsg 

Related  Messages 

• M M_SETITEM  ATTR 
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Enable  Menu  Item 


Example  Code 

This  example  uses  WinEnableMenultem  to  make  a menu  item  selection  available  when  the  menu  is 
initialized  (WMJNITMENU). 


fdefine  INCL_WINMESSAGEMGR  /*  Window  Message  Functions  */ 
fdefine  INCL_WINMENUS  /*  Window  Menu  Functions  */ 
finclude  <os2.h> 


BOOL  fResult;  /* 
MPARAM  mpl;  /* 
MPARAM  mp2;  /* 
USHORT  usltemld;  /* 
HWND  hwndMenu;  /* 


message-posted  indicator 
Parameter  1 (recti  structure) 
Parameter  2 (frame  boolean) 
menu  item  id 
menu  handle 


*/ 

*/ 

*/ 

*/ 

*/ 


case  WMJNITMENU: 

usltemld  = SHORTlFROMMP(mpl) ; 
hwndMenu  = HWNDFR0MMP(mp2) ; 

/*  enable  menu  item  */ 

fResult  = WinEnableMenuItem(hwndMenu,  usltemld,  TRUE); 
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WinEnablePhysInput 
Enable  Physical  Input 


#define  INCL_WININPUT  /*  Or  use  INCL_WIN  or  INCL_PM  */ 


BOOL  WinEnablePhysInput  (HWND  hwndDeskTop,  BOOL  INewInputState) 


This  function  enables  or  disables  queuing  of  physical  input  (keyboard  or  mouse). 


Parameters 

hwndDeskTop  (HWND)  - input 
Desktop-window  handle: 

HWND_DESKTOP  The  desktop-window  handle 

Other  Specified  desktop-window  handle. 

fNewInputState  (BOOL)  - input 

New  state  for  the  queuing  of  physical  input: 

TRUE  Pointing  device  and  keyboard  input  are  queued 

FALSE  Pointing  device  and  keyboard  input  are  disabled. 

Returns 

Previous  state  for  the  queuing  of  physical  input: 

TRUE  Pointing  device  and  keyboard  input  were  queued 
FALSE  Pointing  device  and  keyboard  input  were  disabled. 

Possible  returns  from  WinGetLastError 

PMERRJNVALID  HWND  An  invalid  window  handle  was  specified. 

Related  Functions 

• WinFocusChange 

• WinGetKeyState 

• WinGetPhysKeyState 

• WinQueryFocus 

• WinSetFocus 

• WinSetKeyboardStateTable 

Example  Code 

This  example  uses  WinEnablePhysInput  to  enable  queuing  of  physical  input  (pointing  device  and 
keyboard). 

fdefine  INCL_WININPUT  /*  Window  Input  Functions  */ 

linclude  <os2.h> 

BOOL  fOldlnputState;  /*  previous  queuing  state  */ 

BOOL  fNewInputState=TRUE;/*  new  queuing  state  */ 

/*  enable  queuing  of  physical  input  */ 

fOldlnputState  = WinEnablePhysInput(HWND_DESKTOP,  fNewInputState); 
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Set  Window  Enabled  State 


#define  INCL_WINWINDOWMGR  /*  Or  use  INCL_WIN  or  INCL_PM  7 


BOOL  WinEnableWindow  (HWND  hwnd,  BOOL  fNewEnabled) 


This  function  sets  the  window  enabled  state. 

Parameters 

hwnd  (HWND)  - input 
Window  handle. 

fNewEnabled  (BOOL)  - input 
New  enabled  state: 

TRUE  Set  window  state  to  enabled 

FALSE  Set  window  state  to  disabled. 

Returns 

Window  enabled  indicator: 

TRUE  Window  enabled  state  successfully  updated 
FALSE  Window  enabled  state  not  successfully  updated. 

Possible  returns  from  WinGetLastError 

PMERRJNVALID  HWND  An  invalid  window  handle  was  specified. 

Remarks 

If  the  enable  state  of  hwnd  is  changing,  a WM_ENABLE  message  is  sent  before  this  function  returns. 

If  a window  is  disabled,  its  child  windows  are  also  disabled,  although  they  are  not  sent  the 
WM  ENABLE  message.  Typically,  a window  changes  appearance  when  disabled.  For  example,  a 
disabled  pushbutton  is  displayed  with  half-tone  text. 

If  hwnd  is  disabled,  and  it,  or  one  of  its  descendants,  is  the  focus  window,  that  window  loses  the 
focus,  so  that  no  window  has  the  focus.  However,  a disabled  window  may  subsequently  be  assigned 
the  focus,  in  which  case  it  should  respond  to  keyboard  input. 


Related  Functions 

• WinlsThreadActive 

• WinlsWindow 

• WinlsWindowEnabled 

• WinQueryDesktopWindow 

• WinQueryObjectWindow 

• WinQueryWindowDC 

• WinQueryWindowProcess 

• WinQueryWindowRect 

• WinWindowFromDC 

• WinWindowFromID 

• WinWindowFromPoint 
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WinEnableWindow  - 
Set  Window  Enabled  State 


Related  Messages 

• WM_ENABLE 

Example  Code 

This  example  uses  WinEnableWindow  to  enable  the  system  menu  window  for  the  given  parent 
window,  after  verifying  that  the  parent  window  handle  is  valid  (WinlsWindow),  belongs  to  the  calling 
thread  (WinlsThreadActive),  and  is  not  presently  enabled  (WinlsWindowEnabled). 


fdefine  INCL_WINWINDOWMGR  /*  Window  Manager  Functions  */ 
fdefine  INCL_WINFRAMEMGR  /*  Window  Frame  Functions  */ 
finclude  <os2.h> 

HAB  hab ; /*  anchor-block  handle  */ 
HWND  hwndSysmenu;  /*  system  menu  window  */ 
HWND  hwnd;  /*  parent  window  */ 
BOOL  f Success;  /*  success  indicator  */ 


/*  if  handle  specifies  a valid  window  and  the  window  belongs  to  the 
current  thread,  query  the  enabled  status  of  the  system  menu  */ 
if  (WinIsWindow(hab,  hwnd)  &&  WinlsThreadActi ve(hab)) 

{ 

/*  obtain  handle  for  system  menu  */ 
hwndSysmenu  = WinWindowFromID(hwnd,FID_SYSMENU) ; 

/*  if  system  menu  is  not  enabled,  enable  it  */ 
if  ( ! Wi nlsWi ndowEnabl ed ( hwndSysmenu) ) 

fSuccess  = WinEnableWindow(hwndSysmenu,  TRUE); 

} 
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WinEnableWindowUpdate  - 
Enable  Window  Update 


#define  INCL_WINWINDOWMGR  /*  Or  use  INCL_WIN  or  INCL_PM  */ 


BOOL  WinEnableWindowUpdate  (HWND  hwnd,  BOOL  fNewVIsIblllty) 


This  function  sets  the  window  visibility  state  for  subsequent  drawing. 


Parameters 

hwnd  (HWND)  - input 
Window  handle. 

fNewVIsIblllty  (BOOL)  - input 
New  visibility  state: 

TRUE  Set  window  state  visible 

FALSE  Set  window  state  invisible. 


Returns 

Visibility-changed  indicator: 

TRUE  Window  visibility  successfully  changed 

FALSE  Window  visibility  not  successfully  changed. 

Possible  returns  from  WinGetLastError 

PMERR  INVALID  HWND  An  invalid  window  handle  was  specified. 

PMERR_INVALID_FLAG  An  invalid  bit  was  set  for  a parameter.  Use  constants 

defined  by  PM  for  options,  and  do  not  set  any  reserved 
bits. 


Remarks 

This  function  can  be  used  to  defer  drawing  when  making  a series  of  changes  to  the  window.  The 
window  can  be  redrawn  by  use  of  the  WinShowWindow  function. 

WS_VISIBLE  is  set  to  fNewVisibility  without  causing  redrawing.  This  implies  that  if  the  window  was 
previously  visible,  it  remains  visible  on  the  device  when  WS_VISIBLE  is  reset,  and  conversely,  if  the 
window  was  previously  invisible,  it  is  not  shown  when  WS_VISIBLE  is  set.  If  fNewVisibility  is  set  to 
TRUE,  any  subsequent  drawing  into  the  window  is  visible.  If  fNewVisibility  is  set  to  FALSE,  any 
subsequent  drawing  into  the  window  is  not  visible. 

If  the  value  of  the  WS_VISIBLE  style  bit  has  been  changed,  the  WM  SHOW  message  is  sent  to  the 
window  of  hwnd  before  the  call  returns.  This  function  is  usually  used  to  disable  drawing  before 
making  a series  of  changes  to  a window  to  prevent  unnecessary  drawing.  To  show  a window  and 
ensure  that  it  is  redrawn  after  calling  the  WinEnableWindowUpdate  function  with  fNewVisibility  set  to 
FALSE,  use  the  WinShowWindow  function  with  fNewVisibility  set  to  TRUE. 

Any  alteration  to  the  appearance  of  a window  disabled  for  window  update  is  not  presented. 
Therefore,  the  application  must  ensure  that  the  window  is  redrawn.  In  particular,  if  a window  is 
destroyed  while  in  this  state  its  image  is  not  removed  from  the  display.  After  window  updating  is 
reenabled,  the  application  should  ensure  that  the  window  gets  totally  invalidated  so  that  it  repaints. 
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WinEnableWindowUpdate 
Enable  Window  Update 


Related  Functions 

• WinBeginPaint 

• WinEndPaint 

• WinExcludellpdateRegion 

• WinGetClipPS 

• WinGetPS 

• WinGetScreenPS 

• WinlnvalidateRect 

• WinlnvalidateRegion 

• WinlsWindowShowing 

• WinlsWindowVisible 

• WinLockVisRegions 

• WinOpenWindowDC 

• WinQueryllpdateRect 

• WinQueryUpdateRegion 

• WinRealizePalette 

• WinReleasePS 

• WinShowWindow 

• WinllpdateWindow 

• WinValidateRect 

• WinValidateRegion 

Related  Messages 

• WM_ERASEWINDOW 

• WM_PAINT 

Example  Code 

This  example  uses  WinEnableWindowUpdate  to  set  a window's  WS_VISIBLE  style  to  visible  and 
cause  the  window  to  be  updated  by  a WM_PAINT  message. 

Idefine  INCL_WINWINDOWMGR  /*  Window  Manager  Functions  */ 

finclude  <os2.h> 

HWND  hwnd;  /*  parent  window  */ 

BOOL  fSuccess;  /*  success  indicator  */ 

case  WMCREATE: 

/*  if  window  has  WS_VISIBLE  off,  set  state  to  visible  */ 
if  (IWinlsWindowVisible(hwnd)) 

{ 

/*  set  state  to  visible  and  cause  WM_PAINT  message  */ 
fSuccess  = WinEnableWindowUpdate (hwnd,  EWUF_ENABLE) ; 

} 
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WinEndEnumWindows  - 
End  Window  Enumeration 


#define  INCL_WINWINDOWMGR  /*  Or  use  INCL.WIN  or  INCL_PM  */ 


BOOL  WinEndEnumWindows  (HENUM  henum) 


This  function  ends  the  enumeration  process  for  a specified  enumeration. 

Parameters 

henum  (HENUM)  - input 
Enumeration  handle. 

Returned  by  previous  call  to  the  WinBeginEnumWindows  call. 

Returns 

Success  indicator: 

TRUE  Successful  completion 
FALSE  Error  occurred. 

Possible  returns  from  WinGetLastError 

PMERR  INVALID  HENUM  An  invalid  enumeration  handle  was  specified. 

Remarks 

This  function  destroys  the  window  hierarchy  remembered  by  the  WinBeginEnumWindows  function. 
After  this  function,  the  henum  parameter  is  no  longer  valid. 


Related  Functions 

• WinBeginEnumWindows 

• WinEnumDIgltem 

• WinGetNextWindow 

• WinlsChild 

• WinMultWindowFromIDs 

• WinQueryWindow 

• WinSetOwner 

• WinSetParent 
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WinEndEnumWindows  - 
End  Window  Enumeration 


Example  Code 

This  example  ends  the  child  window  enumeration  and  releases  the  enumeration  handle  supplied  by 
WinBeginEnumWindows  after  WinGetNextWindow  has  enumerated  all  immediate  children  of  the 
Desktop. 


# define  INCL_WINWINDOWMGR  /*  Window  Manager  Functions  */ 

linclude  <os2.h> 


HWND  hwndParent; 

HWND  hwndNext; 

HENUM  henum; 

BOOL  f Success; 

SHORT  sRetLen; 

SHORT  sLength  = 10; 
char  pchBuffer[10] ; 


/*  Handle  of  the  window  whose  child  windows 


are  to  be  enumerated  */ 
/*  current  enumeration  handle  */ 
/*  enumeration  handle  */ 
/*  success  indicator  */ 
/*  returned  string  length  */ 
/*  string  buffer  length  */ 
/*  string  buffer  */ 


hwndParent  = HWND_DESKTOP; 


henum  = Wi nBeginEnumWindows (hwndParent) ; 


while  ((hwndNext  = WinGetNextWindow(henum))  !=  NULLHANDLE)  { 


} 

f Success  = WinEndEnumWindows  (henum); 
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WinEndPaint  - 
End  Paint 


#define  INCL_WINWINDOWMGR  /*  Or  use  INCL_WIN  or  INCL_PM.  Also  in  COMMON  section  */ 


BOOL  WinEndPaint  (HPS  hps) 


This  function  indicates  that  the  redrawing  of  a window  is  complete,  generally  as  part  of  the 
processing  of  a WMPAINT  message. 


Parameters 

hps  (HPS)  - input 

Presentation-space  handle. 

Handle  of  the  presentation  space  that  is  used  for  drawing  and  that  is  returned  by  a previous  call 
to  the  WinBeginPaint  function. 


Returns 

Success  indicator: 

TRUE  Successful  completion 
FALSE  Error  occurred. 

Remarks 

The  presentation  space  is  restored  to  its  state  before  the  WinBeginPaint  function: 

• Cache  presentation  space  is  returned  to  the  cache. 

• Other  presentation  spaces  have  their  original  drawing  state  restored,  including  reassociating  the 
original  device  context  (if  there  was  one). 

If  the  pointer  is  hidden  by  the  WinBeginPaint  function,  it  is  reshown  by  this  function. 

Any  child  windows  having  a synchronous  painting  style  of  the  window  associated  with  the 
presentation  space  are  updated  during  the  processing  of  this  function,  if  they  have  non-NULL  update 
regions. 


Related  Functions 

• WinBeginPaint 

• WinEnableWindowUpdate 

• WinExcludeUpdateRegion 

• WinGetClipPS 

• WinGetPS 

• WinGetScreenPS 

• WinlnvalidateRect 

• WinlnvalidateRegion 

• WinlsWindowShowing 

• WinlsWindowVisible 

• WinLockVisRegions 

• WinOpenWindowDC 

• WinQueryUpdateRect 

• WinQueryUpdateRegion 

• WinRealizePalette 

• WinReleasePS 

• WinShowWindow 

• WinUpdateWindow 

• WinValidateRect 
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WinEndPaint  - 
End  Paint 


• WinValidateRegion 

Related  Messages 

• WM_PAINT 

Example  Code 

This  example  uses  WinEndPaint  to  end  the  update  of  a region  and  release  the  presentation  space 
obtained  by  WinBeginPaint. 


fdefine  INCL_WINWINDOWMGR  /*  Window  Manager  Functions  */ 

linclude  <os2.h> 

HWND  hwnd;  /*  parent  window  */ 

RECTL  rcl;  /*  update  region  */ 

HPS  hps;  /*  presentation-space  handle  */ 

case  WM_PAINT : 

hps  = WinBeginPaint (hwnd,  /*  handle  of  the  window  */ 


NULLHANOLE,  /*  get  a cache  presentation  space  */ 

&rcl);  /*  receives  update  rectangle  */ 

WinFil 1 Rect(hps,  &rcl , CLR_WHITE) ; 

WinEndPaint(hps) ; 
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WinEnumClipbrdFmts  - 
Enumerate  Clipboard  Formats 


#define  INCLJVINCLIPBOARD  /*  Or  use  INCL_WIN  or  INCL_PM  */ 


ULONG  WinEnumClipbrdFmts  (HAB  hab,  ULONG  ulPrev) 


This  function  enumerates  the  list  of  clipboard  data  formats  available  in  the  clipboard. 


Parameters 

hab  (HAB)  - input 

Anchor-block  handle. 

ulPrev  (ULONG)  - input 

Previous  clipboard-data  format  index. 

Specifies  the  index  of  the  last  clipboard  data  format  enumerated  using  this  function. 

This  should  start  at  zero,  in  which  instance  the  first  available  format  is  obtained.  Subsequently, 
it  should  be  set  to  the  last  format  index  value  returned  by  this  function. 


Returns 

Next  clipboard-data  format  index: 

0 Enumeration  is  complete;  that  is,  there  are  no  more  clipboard  formats  available. 
Other  Index  of  the  next  available  clipboard-data  format  in  the  clipboard. 

Remarks 

The  clipboard  should  be  open  before  this  function  is  used. 


Related  Functions 

• WinCloseClipbrd 

• WinEmptyClipbrd 

• WinOpenClipbrd 

• WinQueryClipbrdData 

• WinQueryClipbrdFmtlnfo 

• WinQueryClipbrdOwner 

• WinQueryClipbrdViewer 

• WinSetClipbrdData 

• WinSetClipbrdOwner 

• WinSetClipbrdViewer 
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WinEnumClipbrdFmts  - 
Enumerate  Clipboard  Formats 


Example  Code 

This  example  enumerates  and  counts  the  available  clipboard  data  formats  for  the  clipboard  opened 
by  WinOpenClipbrd. 

Idefine  INCL_WINCLIPBOARD  /*  Window  Clipboard  Functions  */ 

linclude  <os2.h> 


BOOL  f Success;  /*  success  indicator  */ 
HAB  hab;  /*  anchor-block  handle  */ 
ULONG  ulNext;  /*  next  format  index  */ 
ULONG  ulPrev;  /*  previous  format  index  */ 
ULONG  ulNumFormats=0;  /*  number  of  available  formats  */ 


fSuccess  = WinOpenCl ipbrd(hab) ; 

if  (fSuccess) 

{ 

ulPrev  = 0; 

/*  enumerate  formats  and  maintain  count  */ 
while  ((ulNext  = WinEnumClipbrdFmts (hab,  ulPrev))  !=  0) 
{ 

ulNumFormats++; 
ulPrev  = ulNext; 

} 

} 
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WinEnumDIgltem  - 
Enumerate  Dialog  Item 

#define  INCL_WINDIALOGS  /*  Or  use  INCL_WIN  or  INCL_PM  7 
HWND  WinEnumDIgltem  (HWND  hwndDIg,  HWND  hwnd,  ULONG  ulCode) 

This  function  returns  the  window  handle  of  a dialog  item  within  a dialog  window. 

Parameters 

hwndDIg  (HWND)  - input 
Dialog-window  handle. 

hwnd  (HWND)  - input 
Child-window  handle. 

This  may  be  an  immediate  child  of  the  dialog  window  or  a window  lower  in  the  window 
hierarchy,  such  as  a child  of  a child  window. 

NULLHANDLE  can  be  specified  if  ulCode  is  EDI_FIRSTTABITEM  or  EDI_LASTTABITEM. 

ulCode  (ULONG)  - input 
Item-type  code. 

Determines  the  type  of  dialog  item  to  return. 

EDI_PREVTABITEM  Previous  item  with  style  WS_TABSTOP.  Wraps  around  to  end  of  dialog 
item  list  when  beginning  is  reached. 

EDI  NEXTTABITEM  Next  item  with  style  WS_TABSTOP.  Wraps  around  to  beginning  of 
dialog  item  list  when  end  is  reached. 

EDIFIRSTTABITEM  First  item  in  dialog  with  style  WS_TABSTOP.  hwnd  is  ignored. 

EDM.ASTTABITEM  Last  item  in  dialog  with  style  WS_TABSTOP.  hwnd  is  ignored. 

EDI  PREVGROUPITEM  Previous  item  in  the  same  group.  Wraps  around  to  end  of  group  when 
the  start  of  the  group  is  reached.  For  information  on  the  WS_GROUP 
style,  see  “Window  Styles"  on  page  12-2. 

EDI  NEXTGROUPITEM  Next  item  in  the  same  group.  Wraps  around  to  beginning  of  group 
when  the  end  of  the  group  is  reached. 

EDI  FIRSTGROUPITEM  First  item  in  the  same  group. 

EDI_LASTGROUPITEM  Last  item  in  the  same  group. 

Returns 

Item-window  handle. 

As  dictated  by  ulCode. 

The  window  is  always  an  immediate  child  of  hwndDIg,  even  if  hwnd  is  not  an  immediate  child 
window. 

Possible  returns  from  WinGetLastError 

PMERRJNVALIDHWND  An  invalid  window  handle  was  specified. 
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WinEnumDIgltem  - 
Enumerate  Dialog  Item 


Related  Functions 

• WinBeginEnumWindows 

• WinEndEnumWindows 

• WinGetNextWindow 

• WinlsChild 

• WinMultWindowFromIDs 

• WinQueryWindow 

• WinSetOwner 

• WinSetParent 

Example  Code 

This  example  uses  WinEnumDIgltem  to  query  the  first  dialog  item  for  each  immediate  child  of  the 
specified  dialog  window.  The  immediate  children  are  enumerated  using  a WinBeginEnumWindows 
WinGetNextWindow  - WinEndEnumWindows  loop. 


Idefine  INCL_WINDIALOGS  /*  Window  Dialog  Mgr  Functions  */ 
Idefine  INCL_WINWINDOWMGR  /*  Window  Manager  Functions  */ 
linclude  <os2.h> 

HWND  hwndDlg;  /*  Handle  of  the  parent  dialog  window  */ 
HWND  hwndChild;  /*  current  dialog  child  */ 
HWND  hwndltem;  /*  first  dialog  item  */ 
HENUM  henum;  /*  enumeration  handle  */ 
BOOL  f Success;  /*  success  indicator  */ 


henum  = WinBeginEnumWindows (hwndDlg) ; 

while  ((hwndChild  = WinGetNextWindow(henum))  !=  NULL) 

hwndltem  = WinEnumDlgItem(hwndDlg,  hwndChild,  EDI_FIRSTTABITEM) ; 

fSuccess  = WinEndEnumWindows  (henum); 
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WinEnumObjectClasses  - 
Enumerate  Object  Classes 


#define  INCL_WINWORKPLACE 


BOOL  WinEnumObjectClasses  (POBJCLASS  pObjClass,  PULONG  pSIze) 


The  WinEnumObjectClasses  function  will  return  a list  of  all  workplace  object  classes  that  have  been 
registered. 


Parameters 

pObjClass  (POBJCLASS)  - input 

A pointer  to  a buffer  to  be  filled  with  information  about  the  registered  workplace  object  classes. 
pSIze  (PULONG)  - input/output 

Length  of  the  pObjClass  buffer  in  bytes.  If  pObjClass  is  NULL,  the  actual  size  of  pObjClass  is 
returned  in  pSize 


Returns 

Success  indicator: 

TRUE  Successful  completion 
FALSE  Error  occurred. 

Remarks 

WinEnumObjectClasses  will  return  a buffer  containing  all  workplace  object  classes  that  are  currently 
registered  with  the  system.  Workplace  object  classes  are  registered  with  the  system  through  the 
function  call  WinRegisterObjectClass. 

Related  Functions 

• WinRegisterObjectClass 

• WinReplaceObjectClass 
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WinEqualRect  - 
Equal  Rectangle 


#define  INCL_WINRECTANGLES  /*  Or  use  INCL_WIN  or  INCL_PM  */ 


BOOL  WinEqualRect  (HAB  hab,  PRECTL  prcIRectl,  PRECTL  prclRect2) 


This  function  compares  two  rectangles  for  equality. 


Parameters 

hab  (HAB)  - input 

Anchor-block  handle. 

prcIRectl  (PRECTL)  - input 
First  rectangle. 

Note:  The  value  of  each  field  in  this  structure  must  be  in  the  range  —32  768  through  32  767.  The 
datatype  WRECT  can  also  be  used,  if  supported  by  the  language. 

prclRect2  (PRECTL)  - input 
Second  rectangle. 

Note:  The  value  of  each  field  in  this  structure  must  be  in  the  range  —32  768  through  32  767.  The 
data  type  WRECT  can  also  be  used,  if  supported  by  the  language. 


Returns 

Equality  indicator: 

TRUE  Rectangles  are  identical 

FALSE  Rectangles  are  not  identical,  or  an  error  occurred. 

Remarks 

If  both  rectangles  are  empty  (for  example,  yTop  is  equal  to  y Bottom  or  xRight  is  equal  to  xLeft),  they 
are  considered  equal  even  if  the  actual  coordinate  values  are  different. 


Related  Functions 

• WinCopyRect 

• WinFillRect 

• WinlnflateRect 

• WinlntersectRect 

• WinlsRectEmpty 

• WinOffsetRect 

• WinPtlnRect 

• WinSetRect 

• WinSetRectEmpty 

• WinSubtractRect 

• WinUnionRect 
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WinEqualRect  - 
Equal  Rectangle 


Example  Code 

This  example  compares  two  rectangles  for  equality. 

Idefine  INCL_WINRECT ANGLES  /*  Window  Rectangle  Functions  */ 

finclude  <os2.h> 


BOOL  f Equal ; /*  equal  indicator  */ 
HAB  hab;  /*  anchor-block  handle  */ 
RECTL  prclRectl  = {0,0,100,100};  /*  first  rectangle  */ 
RECTL  prclRect2  = {0,0,200,200};  /*  second  rectangle  */ 


fEqual  = WinEqualRect(hab,  &prclRectl,  &prclRect2); 
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WinExcludeUpdateRegion 
Exclude  Update  Region 


#define  INCL_WINWINDOWMGR  /*  Or  use  INCL_WIN  or  INCL_PM  */ 


LONG  WinExcludeUpdateRegion  (HPS  hps,  HWND  hwnd) 


This  function  subtracts  the  update  region  (invalid  region)  of  a window  from  the  clipping  region  of  a 
presentation  space. 


Parameters 

hps  (HPS)  - input 

Presentation-space  handle  whose  clipping  region  is  to  be  updated. 

hwnd  (HWND)  - input 
Window  handle. 

Handle  of  window  whose  update  region  is  subtracted  from  the  clipping  region  of  the  presentation 
space. 


Returns 

Complexity  value. 

This  indicates  the  resulting  form  of  the  clipping  area.  The  values  and  meanings  of  this 
parameter  are  defined  in  the  GpiCombineRegion  function. 


Complexity  of  resulting  region/error  indicator: 
EXRGN_NULL  Null  Region 

EXRGN_RECT  Rectangle  region 

EXRGN_COMPLEX  Complex  region 
EXRGN  ERROR  Error. 


Possible  returns  from  WinGetLastError 

PMERR  INVALID  HWND  An  invalid  window  handle  was  specified. 


Remarks 

This  function  is  typically  used  to  prevent  drawing  into  parts  of  a window  that  are  known  to  be  invalid, 
as  during  an  incremental  update  optimization  process. 

It  is  the  application’s  responsibility  to  reset  the  clipping  region  when  necessary. 
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WinExcludeUpdateRegion  - 
Exclude  Update  Region 


Related  Functions 

• WinBeginPaint 

• WinEnableWindowUpdate 

• WinEndPaint 

• WinGetClipPS 

• WinGetPS 

• WinGetScreenPS 

• WinlnvalidateRect 

• WinlnvalidateRegion 

• WinlsWindowShowing 

• WinlsWindowVisible 

• WinLockVisRegions 

• WinOpenWindowDC 

• WinQueryllpdateRect 

• WinQueryllpdateRegion 

• WinRealizePalette 

• WinReleasePS 

• WinShowWindow 

• WinllpdateWindow 

• WinValidateRect 

• WinValidateRegion 

Example  Code 

This  example  uses  WinExcludeUpdateRegion  to  prevent  drawing  into  the  window's  known  invalid 
regions  (to  optimize  updates)  by  excluding  the  window's  update  region  from  the  clipping  region  of 
the  presentation  space.  The  clipping  region  will  need  to  be  reset  later  by  the  application,  which  can 
accomplished  using  GpilntersectClipRectangle  with  the  rectangle  comprising  the  window  as  input. 


fdefine  INCL_WINWINDOWMGR  /*  Window  Manager  Functions  */ 
fdefine  INCL_GPIREGIONS  /*  Region  functions  */ 
finclude  <os2.h> 

LONG  1 Complexity;  /*  clipping  complexity/error  return  */ 
HWNO  hwnd;  /*  parent  window  */ 
RECTL  rcl ; /*  update  region  */ 
HPS  hps;  /*  presentation-space  handle  */ 


case  WM_PAINT : 

IComplexity  = WinExcludeUpdateRegion(hps,  hwnd); 

hps  = WinBeginPaint (hwnd,  /*  handle  of  the  window  */ 

NULLHANDLE,  /*  get  a cache  presentation  space  */ 

&rcl);  /*  receives  update  rectangle  */ 

WinFillRect(hps,  &rcl , CLR_WHITE) ; 

WinEndPaint(hps) ; 
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WinFileDIg  - 
Standard  File  Dialog 


#define  INCL_WINSTDFILE 


HWND  WlnFlieDig  (HWND  hwndParent,  HWND  hwndOwner,  PFILEDLG  pfdFlledlg) 


This  function  creates  and  displays  the  file  dialog  and  returns  the  user’s  selection  or  selections. 


Parameters 

hwndParent  (HWND)  - input 
Parent-window  handle. 

Parent-window  handle  of  the  created  dialog  window. 

HWND_DESKTOP  The  desktop  window. 

Other  Specified  window. 

hwndOwner  (HWND)  - input 

Requested  owner-window  handle. 

Requested  owner-window  handle  of  the  created  dialog  window. 

The  actual  owner  window  is  calculated  using  the  algorithm  specified  i the  description  of  the 
WinLoadDIg  function. 

pfdFlledlg  (PFILEDLG)  - input 
Pointer. 

Pointer  to  a FILEDLG  structure. 

Returns 

File  dialog  window  handle. 

If  the  FDS_MODELESS  flag  is  set  by  the  application,  the  return  value  is  the  window  handle  of  the 
file  dialog,  or  NULLHANDLE  if  the  dialog  cannot  be  created.  If  the  FDS_MODELESS  flag  is  not 
set,  the  return  value  is  TRUE  if  dialog  creation  is  successful,  or  NULLHANDLE  if  it  is 
unsuccessful. 

Remarks 

The  pfdFiledlg  parameter  is  required  and  the  FILEDLG  structure  must  be  properly  initialized. 

On  return,  the  FILEDLG  structure  is  updated  with  any  user  alterations,  and  the  IReturn  field  is  set  to 
the  value  returned  by  the  file  dialog's  WinDismissDIg  function.  By  default,  this  is  the  ID  of  the 
pushbutton  pressed  to  dismiss  the  dialog,  DID_OK  or  DID_CANCEL,  unless  the  application  supplied 
additional  pushbuttons  in  its  template. 

For  convenience,  the  pointer  to  the  FILEDLG  structure  is  placed  in  the  QWLJJSER  field  of  the 
dialog’s  frame  window.  If  in  a custom  file  dialog  procedure  the  pointer  to  the  FILEDLG  structure  is 
desired,  it  should  be  queried  from  the  frame  window  with  the  WinQueryWindowULong  function. 

To  subclass  the  default  file  dialog  with  a new  template,  the  application  must  give  the  module  and  ID 
of  the  new  file  dialog  template  and  the  address  of  a dialog  procedure  for  message  handling.  Window 
IDs  in  the  range  X‘0000’  through  X’OFFF’  are  reserved  for  the  standard  file  dialog  controls.  IDs  from 
outside  this  range  must  be  chosen  for  any  controls  or  windows  added  to  a custom  file  dialog. 

When  a modeless  dialog  is  dismissed,  the  owner  of  the  file  dialog  will  receive  a WM  COMMAND 
message  with  the  ussource  parameter  equal  to  CMDSRC_FILEDLG  and  the  uscmd  parameter  equal 
to  the  ID  of  the  file  dialog. 
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WinFileDIg  - 
Standard  File  Dialog 


Example  Code 

This  example  uses  WinFileDIg  to  create  and  display  a single  file  selection  dialog  using  the  system 
default  open  file  dialog  template  and  procedure. 


# define  INCL_WINSTDFILE  /*  Window  Standard  File  Functions  */ 

linclude  <os2.h> 

FILEDLG  pfdFiledlg;  /*  File  dialog  info  structure  */ 

char  pszTitle[10]  = "Open  File";  /*  Title  of  dialog  */ 

char  pszFullFile[CCHMAXPATH]  = "*.C";/*  File  filter  string  */ 

HWND  hwndMain;  /*  Window  that  owns  the  file  dialog  */ 

HWND  hwndDlg;  /*  File  dialog  window  */ 

j ******* ********************************************************** j 

/*  Initially  set  all  fields  to  0 */ 


j ******* ****** ****** ******************* ****** ****** *************** j 

memset(&pfdFiledlg,  0,  sizeof(FILEDLG)) ; 

j ************** ****************** ****** ****** ****** ****** ********* j 

/*  Initialize  those  fields  in  the  FILEDLG  structure  that  are  */ 
/*  used  by  the  application  */ 

j •k’k-k-k-k-k-k-kic-k-k-kie-k-k-kic’k-k-kie-k-k-kic’k-k-kic-k-k-kie-k-k-kic-k-k-kic’k-k-kie-k-k-kie-k-k-k-k-k-k-kic-k-k-kie-k-k-kie  j 

pfdFiledlg.cbSize  = sizeof(FILEDLG) ; /*  Size  of  structure  */ 

pfdFiledlg.fi  = FDS_HELPBUTTON  | FDS_CENTER  | FDS_0PEN_DIAL0G; 

/*  FDS_*  flags  */ 

pfdFiledlg. pszTitle  = pszTitle;  /*  Dialog  title  string  */ 
strcpy(pfdFiledlg.szFullFile,  pszFull File) ; /*  Initial  path,  */ 

/*  file  name,  or  */ 

/*  file  filter  */ 

j-k’kic-k-k-k-k-kie-k-k-k-k-k-k-k-k-kie-k-k-k-k-kie-kle-k-k-k-k-k-k-k-k-k-kic-k-k-k-k-kie-k-k-k-k-k'kieieieie-kirkirkie-kie-kirk  j 

/*  Display  the  dialog  and  get  the  file  */ 

j *********** ****** ****** ****** ****** ****************************** j 

hwndDlg  = WinFileDlg(HWND_DESKTOP,  hwndMain,  &pfdFi 1 edl g ) ; 

if  (hwndDlg  &&  (pfdFi 1 edl g.l Return  ==  DID_0K) ) 

{ 

j ***************** ****** ****** ****** ******** ******************* j 

/*  Upon  successful  return  of  a file,  open  it  for  reading  and  */ 
/*  further  processing  */ 

j ************************************************************** j 

} 
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WinFillRect  - 
Fill  Rectangle 


#define  INCL_WINWINDOWMGR  /*  Or  use  INCL_WIN  or  INCL_PM.  Also  in  COMMON  section  */ 


BOOL  WinFillRect  (HPS  hps,  PRECTL  prciRect,  LONG  IColor) 


This  function  draws  a filled  rectangular  area. 


Parameters 

hps  (HPS)  - input 

Presentation-space  handle. 

This  can  be  either  a micro-presentation  space  or  a normal  presentation  space. 

prciRect  (PRECTL)  - input 

Rectangle  to  be  filled,  in  window  coordinates. 

Points  on  the  left  and  bottom  boundaries  of  the  rectangle  are  included  in  the  fill,  but  points  on  the 
right  and  top  boundaries  are  not,  except  where  they  are  also  on  the  left  and  bottom  boundaries; 
that  is,  the  top-left  and  bottom-right  corners. 

Note:  The  value  of  each  field  in  this  structure  must  be  in  the  range  —32  768  through  32  767.  The 
data  type  WRECT  can  also  be  used,  if  supported  by  the  language. 

IColor  (LONG)  - input 

Color  with  which  to  fill  the  rectangle. 

This  is  either  a color  index,  or  an  RGB  color  value,  depending  upon  whether  and  how  a logical 
color  table  has  been  loaded.  (See  the  GpiCreateLogColorTable  and  GpiSetColor  functions.) 


Returns 

Success  indicator; 

TRUE  Successful  completion 
FALSE  Error  occurred. 


Remarks 

This  function  does  not  change  any  presentation  space  state. 

This  function  must  only  be  used  in  draw  mode  (DMDRAW)  to  a screen  device  context. 

If  an  empty  rectangle  is  specified,  this  function  draws  nothing  and  completes  successfully  (that  is, 
TRUE  is  returned). 
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WinFillRect  - 
Fill  Rectangle 


Related  Functions 

• WinDrawBitmap 

• WinDrawBorder 

• WinDrawPointer 

• WinDrawText 

• WinGetSysBitmap 

• WinlnvertRect 

• WinQueryPresParam 

• WinRemovePresParam 

• WinScrollWindow 

• WinSetPresParam 

• WinCopyRect 

• WinEqualRect 

• WinlnflateRect 

• WinlntersectRect 

• WinlsRectEmpty 

• WinOffsetRect 

• WinPtlnRect 

• WinSetRect 

• WinSetRectEmpty 

• WinSubtractRect 

• WinllnionRect 

Example  Code 

This  example  fills  an  update  rectangle  with  a white  background  in  response  to  the  WM_PAINT 
message,  after  obtaining  a presentation  space  handle  via  WinBeginPaint. 


Idefine  INCL_WINWINDOWMGR  /*  Window  Manager  Functions  */ 
finclude  <os2.h> 

BOOL  f Success;  /*  success  indicator  */ 
HAB  hab;  /*  anchor-block  handle  */ 
RECTL  prclRectl  = {0,0,100,100};  /*  fill  rectangle  */ 
LONG  lColor=CLR_WHITE;  /*  fill  color  */ 
HWND  hwnd;  /*  client  window  handle  */ 
HPS  hps;  /*  presentation-space  handle  */ 


case  WM_PAINT : 

hps  = WinBeginPaint(hwnd,  NULLHANDLE,  SprclRectl); 
fSuccess  = WinFillRect(hps,  SprclRectl,  IColor); 
WinEndPaint(hps) ; 
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WinFindAtom 
Find  Atom 


#define  INCL_WINATOM  /*  Or  use  INCL_WIN  or  INCL_PM  */ 


ATOM  WinFindAtom  (HATOMTBL  hatomtblAtomTbl,  PSZ  pszAtomName) 


This  function  finds  an  atom  in  the  atom  table. 


Parameters 

hatomtblAtomTbl  (HATOMTBL)  - input 
Atom-table  handle. 

This  is  the  handle  returned  from  a previous  WinCreateAtomTable  or  WinQuerySystemAtomTable 
function. 

pszAtomName  (PSZ)  - input 
Atom  name. 

This  is  a null  terminated  character  string  to  be  found  in  the  table. 

If  the  string  begins  with  a character,  the  five  ASCII  digits  that  follow  are  converted  into  an 
integer  atom. 

If  the  string  begins  with  a “!”  character,  the  next  two  bytes  are  interpreted  as  an  atom. 

If  the  high  order  word  of  the  string  is  -1,  the  low  order  word  is  an  atom. 


Returns 

Atom  value: 

Atom  The  atom  associated  with  the  passed  string 
0 Invalid  atom  table  handle  or  invalid  atom  name  specified. 


Possible  returns  from  WinGetLastError 

PMERRJNVALIDHATOMTBL 
PMERR  INVALID JNTEGER  ATOM 
PM  E R R_IN  V ALIDATOMN  AM  E 
PMERRATOMNAMENOTFOUND 


An  invalid  atom-table  handle  was  specified. 

The  specified  atom  is  not  a valid  integer  atom. 

An  invalid  atom  name  string  was  passed. 

The  specified  atom  name  is  not  in  the  atom  table. 


Remarks 

This  function  is  identical  to  the  WinAddAtom  function,  except  that: 

* If  the  atom  name  is  not  found  in  the  table,  it  is  not  added  to  the  table  and  0 is  returned. 

• If  the  atom  name  is  found  in  the  table,  the  use  count  is  not  incremented. 

Because  integer  atoms  do  not  have  a use  count  and  do  not  actually  occupy  memory  in  the  atom 
table,  this  function  is  identical  to  WinAddAtom  with  respect  to  integer  atoms. 
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WinFindAtom  - 
Find  Atom 


Related  Functions 

• WinAddAtom 

• WinCreateAtomTable 

• WinDeleteAtom 

• WinDestroyAtomTable 

• WinQueryAtomLength 

• WinQueryAtomName 

• WinQueryAtomllsage 

• WinQuerySystemAtomTable 

Example  Code 

This  example  queries  an  Atom  Table  for  the  atom  name  of  a newly  created  atom  'newatom'  and  then 
verifies  that  the  atom  value  returned  by  the  query  matches  the  atom  value  returned  by  WinAddAtom. 


Idefine  INCL_WINATOM  /*  Window  Atom  Functions  */ 
finclude  <os2.h> 

ATOM  atom;  /*  new  atom  value  */ 
ATOM  atomFound;  /*  atom  value  from  WinFindAtom  */ 
HATOMTBL  hatomtblAtomTbl ; /*  atom-table  handle  */ 
char  pszAtomName [10] ; /*  atom  name  */ 
ULONG  ul Initial  = 0;  /*  initial  atom  table  size  (use  default)*/ 
ULONG  ulBuckets  = 0;  /*  size  of  hash  table  (use  default)  */ 
BOOL  atomMatch  = FALSE;  /*  indicates  atom  values  match  */ 


/*  create  atom  table  of  default  size  */ 

hatomtblAtomTbl  = WinCreateAtomTable(ulInitial , ulBuckets); 

/*  define  name  for  new  atom  and  add  to  table  */ 

strcpy(pszAtomName,"newatom") ; 

atom  = WinAddAtom (hatomtblAtomTbl , pszAtomName); 

atomFound  = WinFindAtom(hatomtblAtomTbl , pszAtomName); 

/*  verify  that  the  atom  values  match  */ 
if  (atom  ==  atomFound) 
atomMatch  = TRUE; 
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WinFlashWindow 
Flash  Window 


#define  INCL_WINFRAMEMGR  /*  Or  use  INCL_WIN  or  INCL_PM  7 


BOOL  WinFlashWindow  (HWND  hwnd,  BOOL  (Flash) 


This  function  starts  or  stops  a window  flashing. 


Parameters 

hwnd  (HWND)  - input 

Handle  of  window  to  be  flashed. 

(Flash  (BOOL)  - input 

Start-flashing  indicator: 

TRUE  Start  window  flashing 

FALSE  Stop  window  flashing. 

Returns 

Success  indicator: 

TRUE  Successful  completion 
FALSE  Error  occurred. 

Possible  returns  from  WinGetLastError 

PMERR  INVALID  HWND  An  invalid  window  handle  was  specified. 

Remarks 

Flashing  a window  brings  the  user’s  attention  to  a window  that  is  not  the  active  window,  where  some 
important  message  or  dialog  must  be  seen  by  the  user. 

Flashing  is  typically  done  by  inverting  the  title  bar  continuously.  The  alarm  is  sounded  for  the  first 
five  flashes. 

Note:  It  should  be  used  only  for  important  messages,  for  example,  where  some  component  of  the 
system  is  failing  and  requires  immediate  attention  to  avoid  damage. 


Related  Functions 

• WinAlarm 

• WinMessageBox 
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WinFlashWindow  - 
Flash  Window 


Example  Code 

This  example  uses  WinFlashWindow  to  flash  an  inactive  window  to  draw  the  user's  attention  to  an 
important  message  in  the  window. 


fdefine  INCL_WINFRAMEMGR  /*  Window  Frame  Functions  */ 
fdefine  INCL_WINDIALOGS  /*  Window  Dialog  Mgr  Functions  */ 
finclude  <os2.h> 


*/ 
*/ 

/*  flash  window  to  get  user's  attention  */ 
fSuccess  = WinFlashWindow(hwnd,  TRUE); 


BOOL  fSuccess;  /*  Success  indicator 

HWND  hwnd;  /*  window  handle 


/*  vital  message  is  displayed  */ 


Wi nMessageBox ( HWND_DESKTOP , 
hwnd, 

"Important  message:  must 
"Vital  message", 

0, 

MB_N0IC0N  | MB_0K) ; 


/*  client-window  handle  */ 
be  seen  by  user",/*  message  */ 
/*  title  of  the  message  */ 

/*  message  box  id  */ 

/*  icon  and  button  flags  */ 
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WinFocusChange  - 
Change  Focus  Window 


#define  INCL_WININPUT  /*  Or  use  INCL_WIN  or  INCL_PM.  Also  in  COMMON  section  7 


BOOL  WinFocusChange  (HWND  hwndDeskTop,  HWND  hwndNewFocus, 
ULONG  fIFocusChange) 


This  function  changes  the  focus  window. 

Parameters 

hwndDeskTop  (HWND)  - input 
Desktop- window  handle: 

HWND_DESKTOP  The  desktop-window  handle 

Other  Specified  desktop-window  handle. 

hwndNewFocus  (HWND)  - input 

Window  handle  to  receive  the  focus. 

fIFocusChange  (ULONG)  - input 
Focus  changing  indicators. 

These  indicators  are  passed  on  in  the  WM  FOCUSCHANGE  message: 

FC_NOSETFOCUS 

Do  not  send  the  WM  SETFOCUS  message  to  the  window  receiving  the  focus. 

FC_NOLOSEFOCUS 

Do  not  send  the  WM_SETFOCUS  message  to  the  window  losing  the  focus. 

FC_NOSET  ACTIVE 

Do  not  send  the  WMACTIVATE  message  to  the  window  being  activated. 

FC_NOLOSEACTIVE 

Do  not  send  the  WM  ACTIVATE  message  to  the  window  being  deactivated. 

FC_NOSETSELECTION 

Do  not  send  the  WMSETSELECTION  message  to  the  window  being  selected. 

FC_NOLOSESELECTION 

Do  not  send  the  WM  SETSELECTION  message  to  the  window  being  deselected. 

FC_NOBRINGTOTOP 

Do  not  bring  any  window  to  the  top. 

FC_NOBRINGTOTOPFIRSTWINDOW 

Do  not  bring  the  first  frame  window  to  the  top. 

FC_SET  ACTIVEFOCUS 

Set  the  focus  to  the  child  window  that  previously  had  the  focus  of  the  first  window  in  the 
parentage  of  hwndNewFocus,  which  has  the  CS_FRAME  style. 


Returns 

Success  indicator: 

TRUE  Successful  completion 
FALSE  Error  occurred. 

Possible  returns  from  WinGetLastError 

PMERRJNVALID  HWND  An  invalid  window  handle  was  specified. 
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WinFocusChange  - 
Change  Focus  Window 


Remarks 

This  function  sends  a WMFOCUSCHANGE  message  to  the  window  that  is  losing  the  focus  and  a 
WM_FOCUSCHANGE  message  to  the  window  that  is  receiving  the  focus. 

This  function  fails  if  another  process  or  thread  is  currently  using  this  function. 

Other  messages  may  be  sent  as  a consequence  of  the  frame  control  processing  of  the 
WM  FOCUSCHANGE  (in  Frame  Controls)  message,  depending  on  the  value  of  the  fIFocusChange 
parameter.  These  messages,  if  sent,  are  sent  in  this  order: 

1 . WMSETFOCUS  to  the  window  losing  the  focus. 

2.  WMSETSELECTION  to  the  windows  losing  their  selection. 

3.  WMACTIVATE  to  the  windows  being  deactivated. 

4.  WM  ACTIVATE  to  the  windows  being  activated. 

5.  WM_SETSELECTION  to  the  windows  being  selected. 

6.  WM  SETFOCUS  to  the  window  receiving  the  focus. 

Note:  If  the  WinQueryFocus  function  is  used  during  processing  of  this  function: 

• The  window  handle  of  the  window  losing  the  focus  is  returned  while  the 
WM_FOCUSCHANGE  message  with  the  usSetFocus  parameter  set  to  FALSE  is  being 
processed. 

• The  window  handle  of  the  window  receiving  the  focus  is  returned  while  the 
WM_FOCUSCHANGE  (in  Frame  Controls)  message  with  the  usSetFocus  parameter  set  to 
TRUE  is  being  processed. 

If  the  WinQueryActiveWindow  function  is  used  during  processing  of  this  function: 

• The  window  handle  of  the  window  being  deactivated  is  returned  while  the  WM  ACTIVATE 
message  with  the  usactive  parameter  set  to  FALSE  is  being  processed. 

• The  window  handle  of  the  window  being  activated  is  returned  while  the  WM  ACTIVATE 
message  with  the  usactive  parameter  set  to  TRUE  is  being  processed. 

Also,  there  is  a short  period  during  the  time  after  the  old  active  window  has  acted  on  the 
deactivation  message  and  before  the  new  active  window  has  acted  on  the  activation  message 
when  the  WinQueryActiveWindow  function  returns  NULLHANDLE. 

This  function  should  not  be  made  unless  it  is  directly  or  indirectly  the  result  of  operator  input. 

Even  if  FC_NOSETSELECTION  is  not  specified,  the  WM  SETSELECTION  is  not  sent  to  a frame  window 
that  is  already  selected.  This  can  occur  if  the  focus  is  being  transferred  from  a parent  to  a child 
window  and  FC_NOLOSESELECTION  was  specified. 


Related  Functions 

• WinEnablePhysInput 

• WinGetKeyState 

• WinGetPhysKeyState 

• WinQueryFocus 

• WinSetFocus 

• WinSetKeyboardStateTable 


Related  Messages 

• WM_ACTIVATE 

• WM_FOCUSCHANGE 

• WM_SETFOCUS 

• WM_SETSELECTION 
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WinFocusChange  - 
Change  Focus  Window 


Example  Code 

This  example  uses  WinFocusChange  to  change  the  focus  to  the  selected  window,  using  the  handle 
returned  by  WinQueryFocus. 


fdefine  I NCL_WININPUT  /*  Window  Input  Functions  */ 
linclude  <os2.h> 

HWND  hwndNewFocus ; /*  Handle  of  new  focus  window  */ 
BOOL  fSuccess;  /*  success  indicator  */ 
MPARAM  mpl;  /*  Parameter  1 (select  boolean)  */ 


case  WM_SETSELECTION: 

/*  if  window  is  being  selected,  change  focus  to  the  window  */ 
if  (SHORTFROMMP(mpl) ) 

{ 

if  ((hwndNewFocus  = 

WinQueryFocus (HWND_DESKTOP))  !=  0L) 
fSuccess  = WinFocusChange(HWND_DESKTOP,  hwndNewFocus, 
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WinFontDIg  - 
Standard  Font  Dialog 


#define  INCL_WINSTDFONT 


HWND  WinFontDIg  (HWND  hwndParent,  HWND  hwndOwner,  PFONTDLG  pfntdFontdlg) 


This  dialog  allows  the  user  to  select  a font. 


Parameters 

hwndParent  (HWND)  - input 
Parent-window  handle. 

Parent-window  handle  of  the  created  dialog  window. 

HWND_DESKTOP  The  desktop  window. 

Other  Specified  window. 

hwndOwner  (HWND)  - input 

Requested  owner-window  handle. 

Requested  owner-window  handle  of  the  created  dialog  window. 

The  actual  owner  window  is  calculated  using  the  algorithm  specified  in  the  description  of  the 
WinLoadDIg  function. 

pfntdFontdlg  (PFONTDLG)  - input 
Pointer. 

Pointer  to  an  initialized  FONTDLG  structure. 

Returns 

Font  dialog  window  handle. 

If  the  FNTS_MODELESS  flag  is  set  by  the  application,  the  return  value  is  the  window  handle  of 
the  font  dialog,  or  NULLHANDLE  if  the  dialog  cannot  be  created.  If  the  FNTS_MODELESS  flag  is 
not  set,  the  return  value  is  TRUE  if  dialog  creation  is  successful,  or  NULLHANDLE  if  it  is 
unsuccessful. 

Remarks 

The  pfntdFontdlg  parameter  is  required  and  the  FONTDLG  structure  must  be  properly  initialized. 

Upon  return,  the  FONTDLG  structure  is  updated  with  any  user  alterations  and  the  / Return  field 
contains  the  value  returned  by  the  font  dialog’s  WinDismissDIg  function.  By  default  this  is  the  ID  of 
the  pushbutton  pressed  to  dismiss  the  dialog,  DID_OK  or  DID_CANCEL,  unless  the  application 
supplied  additional  pushbuttons  in  its  template. 

The  pointer  to  the  FONTDLG  structure  is  placed  in  the  QWLJJSER  field  of  the  dialog's  frame  window. 
If  in  a custom  font  dialog  procedure  the  pointer  to  the  FONTDLG  structure  is  desired,  it  should  be 
queried  from  the  frame  window  with  WinQueryWindowULong. 

T o subclass  the  default  font  dialog  with  a new  template,  the  application  must  give  the  module  and  ID 
of  the  new  font  dialog  template  and  the  address  of  a dialog  procedure  for  message  handling. 

Window  IDs  in  the  range  X‘0000’  through  X'OFFF’  are  reserved  for  the  font  dialog  controls.  IDs  from 
outside  this  range  must  be  chosen  for  any  controls  added  to  a custom  font  dialog. 

When  a modeless  dialog  is  dismissed,  the  owner  of  the  font  dialog  will  receive  a WM_COMMAND 
message  with  the  ussource  parameter  equal  to  CMDSRC_FONTDLG  and  the  uscmd  parameter  equal 
to  the  ID  of  the  font  dialog. 
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WinFontDIg  - 
Standard  Font  Dialog 


Example  Code 

This  example  displays  a font  selection  dialog  by  using  WinFontDIg,  which  allows  the  user  to  select 
font. 

Idefine  INCL_WINSTDFONT  /*  Window  Standard  Font  Functions  */ 
linclude  <os2.h> 
linclude  <string.h> 


HPS  hpsScreen; 

FONTDLG  pfdFontdlg; 
HWND  hwndMain; 

HWND  hwndFontDlg; 


/*  Screen  presentation  space  */ 
/*  Font  dialog  info  structure  */ 
/*  Window  that  owns  the  font  dialog  */ 
/*  Font  dialog  window  */ 


char  szFamilyname[FACESIZE] ; 


/ 


*************************************************************** 


/ 


/*  Initially  set  all  fields  to  0 */ 

y***************************************************************  j 

memset(&pfdFontdlg,  0,  si zeof (FONTDLG) ) ; 


'*************************************************************** 


/*  Initialize  those  fields  in  the  FONTDLG  structure  that  are  */ 
/*  used  by  the  application  */ 

j *********************** ********** ****** ************************ j 

pfdFontdlg. cbSize  = si zeof (FONTDLG) ; /*  Size  of  structure  */ 

pfdFontdlg. hpsScreen  = hpsScreen;  /*  Screen  presentation  */ 

/*  space  */ 

szFamilyname[0]  = 0;  /*  Use  default  font  */ 

pfdFontdlg.pszFamilyname  = szFamilyname; 
pfdFontdlg. usFamilyBufLen  = strlen (szFamilyname) ; 
pfdFontdlg. fxPointSize  = MAKEFIXED(10,0) ; /*  Font  point  size  */ 


pfdFontdlg.fi  = FNTS_HELPBUTTON  | FNTS_CENTER;  /*  FNTS_*  flags  */ 


pfdFontdlg. cl rFore  = CLR_BLACK;  /*  Foreground  color  */ 
pfdFontdlg.clrBack  = CLR_WHITE;  /*  Background  color  */ 
pfdFontdlg.fAttrs.usCodePage  = 437;  /*  Code  page  to  select  */ 

/*  from  */ 


j ******** *********** ****** ******** ****************************** j 

/*  Display  the  font  dialog  and  get  the  font  */ 

j *************************************************************** y 

hwndFontDlg  = Wi nFontDl g(HWND_DESKTOP , hwndMain,  SpfdFontdlg) ; 

if  (hwndFontDlg  &&  (pfdFontdlg. 1 Return  ==  DID_OK)) 

{ 

y************************************************************  j 

/*  Upon  successful  return  of  a font,  the  application  can  */ 
/*  use  font  information  selected  by  the  user  to  create  a */ 
/*  font,  load  a font,  and  so  forth  */ 

^************************************************************  j 

> 
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WinFreeErrorlnfo  - 
Free  Error  Information 


#define  INCL_WINERRORS  /*  Or  use  INCL_WIN  or  INCL_PM  */ 


BOOL  WinFreeErrorlnfo  (PERRINFO  perrlErrorlnfo) 


This  function  releases  memory  allocated  for  an  error-information  block. 


Parameters 

perrlErrorlnfo  (PERRINFO)  - input 

Error-information  block  whose  memory  is  to  be  released. 


Returns 

Success  indicator: 

TRUE  Successful  completion 

FALSE  perrlErrorlnfo  is  not  an  error-information  block  for  the  current  thread. 

Related  Functions 

• WinGetErrorlnfo 

• WinGetLastError 

Example  Code 

This  example  frees  memory  allocated  (by  WinGetErrorlnfo)  for  an  error-information  block  using 
WinFreeErrorlnfo. 


fdefine  INCL_WINERRORS  /*  Window  Error  Functions  */ 
linclude  <os2.h> 

BOOL  fSuccess;  /*  success  indicator  */ 
ERRORID  erridErrorCode;/*  last  error  id  code  */ 
PERRINFO  perriErrorlnfo;/*  error  info  structure  */ 
HAB  hab;  /*  anchor-block  handle  */ 


/*  obtain  error  block  and  assign  error  code  */ 
perriErrorlnfo  = WinGetErrorlnfo(hab) ; 
erridErrorCode  = perriErrorInfo->idError; 

/*  free  error  block  */ 

fSuccess  = WinFreeErrorlnfo (perri Errorlnfo) ; 
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WinFreeFileDIgList  - 

Free  Standard  File  Dialog  File  List 


#define  INCL_WINSTDFILE 


BOOL  WinFreeFileDIgList  (PAPSZ  papszFQFIIename) 


This  function  frees  the  storage  allocated  by  the  file  dialog  when  the  FDS_MULTIPLESEL  dialog  flag  is 
set. 

Parameters 

papszFQFIIename  (PAPSZ)  - input 
Pointer. 

Pointer  to  a table  of  pointers  of  fully-qualified  file  names  returned  by  the  dialog. 


Returns 

Success  indicator. 

TRUE  Successful  completion. 
FALSE  Error  occurred. 


Remarks 

When  the  FDS_MULTIPLESEL  style  flag  is  set  and  the  user  selects  one  or  more  files  from  the  file 
name  list  box,  the  fully-qualified  file  names  of  the  selected  files  are  returned  in  th e papszFQFilename 
field  of  the  FILEDLG  structure.  After  the  application  retrieves  all  of  the  information  it  needs  from  the 
papszFQFilename  array,  it  should  call  WinFreeFileDIgList  to  free  the  storage. 


Example  Code 

This  example  uses  the  WinFreeFileDIgList  function  to  deallocate  the  table  of  file  name  pointers 
returned  by  the  WinFileDIg  function  when  the  FDS_MULTIPLESEL  flag  is  set  in  the  fl  field  of  the 
FILEDLG  structure. 


fdefine  INCL_WINSTDFILE  /*  Window  Standard  File  Functions  */ 
linclude  <os2.h> 

BOOL  f Success;  /*  Success  indicator  */ 
FILEDLG  pfdFiledlg;  /*  File  dialog  info  structure  */ 
HWND  hwndMain;  /*  Window  that  owns  the  file  dialog  */ 
HWND  hwndDlg;  /*  File  dialog  window  */ 


y*****************************************************************  y 

/*  initialize  FILEDLG  structure  */ 

y*****************************************************************  y 

pfdFiledlg. cbSize  = sizeof(FILEDLG) ; /*  Size  of  structure  */ 

pfdFiledlg.fi  = FDS_MULTIPLESEL  | FDS_HELPBUTTON  | FDS_CENTER  | 

FDS_0PEN_DIAL0G;  /*  FDS_*  flags  */ 


y*****************************************************************  y 

/*  Set  remaining  fields  here  */ 

/***************************************************************** / 


y ***************************************************************** y 
/*  Display  the  dialog  and  get  the  files  */ 
/*****************************************************************  / 
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WinFreeFileDIgList  - 
Free  Standard  File  Dialog  File  List 


hwndDlg  = Wi nFi 1 eDl g(HWND_DESKTOP , hwndMain,  &pfdFiledlg) ; 

if  (hwndDlg  &&  (pfdFiledlg.l Return  ==  DID_0K)) 

{ 


/ 


************************************************************** 


/ 


/*  Upon  successful  return  of  the  files,  open  them  for  further  */ 


/*  processing  using  the  table  of  file  name  pointers 

/ 


************************************************************** 


y **************************************************************/ 
/*  Find  out  whether  the  pointer  array  was  allocated  */ 

/ 


************************************************************** 


/ 

if  (pfdFiledlg.papszFQFilename) 

y*********************************************************** i 

/*  If  so,  free  the  table  of  file  name  pointers  */ 

I *********************************************************** i 

fSuccess  = WinFreeFileDIgList (pfdFiledlg.papszFQFilename); 
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WinFreeFilelcon  - 
Free  File  Icon 


#define  INCL_WINWORKPLACE 


BOOL  WinFreeFilelcon  (HPOINTER  hptr) 


The  WinFreeFilelcon  function  will  free  the  pointer  to  an  icon  allocated  by  WinLoadFilelcon. 

Parameters 

hptr  (HPOINTER)  - input 

A pointer  to  an  icon  loaded  by  WinLoadFilelcon. 

Returns 

Success  indicator: 

TRUE  Successful  completion 
FALSE  Error  occurred. 

Related  Functions 

• WinSetFilelcon 

• WinLoadFilelcon 
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WinGetClipPS  - 
Get  Clipped  Presentation  Space 


#define  INCL_WINWINDOWMGR  /*  Or  use  INCL_WIN  or  INCL_PM.  Also  in  COMMON  section  */ 


HPS  WinGetClipPS  (HWND  hwnd,  HWND  hwndClIpWIndow,  ULONG  ulCllpflags) 


This  function  obtains  a clipped  cache  presentation  space. 


Parameters 

hwnd  (HWND)  - input 

Handle  of  window  for  which  the  presentation  space  is  required. 

hwndClIpWIndow  (HWND)  - input 
Handle  of  window  for  clipping. 

Values  to  be  specified  can  be  one  of  the  following: 


HWND_BOTTOM  Clip  the  last  window  in  the  sibling  chain  and  continue  clipping  until  the 
window  is  hwnd  or  NULLHANDLE. 

HWND  TOP  Clip  the  first  window  in  the  sibling  chain  and  continue  clipping  until  the 

window  is  hwnd  or  NULLHANDLE. 


NULLHANDLE  Clip  all  siblings  to  the  window  hwnd. 

ulCllpflags  (ULONG)  - input 
Clipping  control  flags. 


next 

next 


PSFCLIPSIBLINGS 

PSFCLIPCHILDREN 

PSFCLIPUPWARDS 


Clip  out  all  siblings  of  hwnd. 

Clip  out  all  children  of  hwnd. 

Taking  hwndClipWindow  as  a reference  window,  clip  out  all 
sibling  windows  before  hwndClipWindow.  This  value  may  not  be 
used  with  PSF_CLIPDOWNWARDS. 


PSF  CLIPDOWNWARDS  Taking  hwndClipWindow  as  a reference  window,  clip  out  all 

sibling  windows  after  hwndClipWindow.  This  value  may  not  be 
used  with  PSF_CLIPUPWARDS. 

PSF  LOCKWINDOWUPDATE  Calculate  a presentation  space  that  keeps  a visible  region  even 

though  output  may  be  locked  by  the  WinLockWindowUpdate 
function. 


PSF_PARENTCLIP  Calculate  a presentation  space  that  uses  the  visible  region  of  the 

parent  of  hwnd  but  with  an  origin  calculated  for  hwnd. 


Returns 

Presentation-space  handle  that  can  be  used  for  drawing. 

Possible  returns  from  WinGetLastError 

PMERRJNVALID  HWND  An  invalid  window  handle  was  specified. 


Remarks 

The  presentation  space  obtained  by  this  function  is  a cache  “micro-presentation  space”  present  in 
the  system.  This  can  be  used  for  simple  drawing  operations  that  do  not  depend  on  long-term  data 
being  stored  in  the  presentation  space. 
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WinGetClipPS  - 

Get  Clipped  Presentation  Space 


Related  Functions 

• WinBeginPaint 

• WinEnableWindowllpdate 

• WinEndPaint 

• WinExcludellpdateRegion 

• WinGetPS 

• WinGetScreenPS 

• WinlnvalidateRect 

• WinlnvalidateRegion 

• WinlsWindowShowing 

• WinlsWindowVisible 

• WinLockVisRegions 

• WinOpenWindowDC 

• WinQueryllpdateRect 

• WinQueryllpdateRegion 

• WinRealizePalette 

• WinReleasePS 

• WinShowWindow 

• WinUpdateWindow 

• WinValidateRect 

• WinValidateRegion 

Example  Code 

This  example  responds  to  an  application  defined  message  (IDM_FILL)  and  uses  WinGetClipPS  to 
obtain  and  associate  a cached  presentation  space  with  a window,  where  the  PS  is  clipped  to  the 
children  of  the  window. 


Idefine  INCL_WINWINDOWMGR.  /*  Window  Manager  Functions  */ 
linclude  <os2.h> 

HWND  hwnd;  /*  PS  window  */ 
HWND  hwndClip;  /*  clipping  window  */ 
RECTL  rcl ; /*  update  region  */ 
HPS  hps;  /*  presentation-space  handle  */ 


case  IDM_FILL: 

hps  = WinGetClipPS(hwnd,  /*  handle  of  the  PS  window  */ 
hwndClip,  /*  handle  of  clipping  window  */ 

PSF_CLIPCHI LDREN) ; /*  clipping  flags  */ 

WinFillRect(hps,  &rcl , CLR_WHITE) ; 

WinReleasePS(hps) ; 
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WinGetCurrentTime  - 
Get  Current  Time 


#define  INCL_WINTIMER  /*  Or  use  INCL.WIN  or  INCL_PM  */ 


ULONG  WinGetCurrentTime  (HAB  hab) 


This  function  returns  the  current  time. 

Parameters 

hab  (HAB)  - input 

Anchor-block  handle. 


Returns 

System-timer  count. 

The  time  is  in  milliseconds,  from  the  system  Initial  Program  Load  (IPL).  This  is  the  same  value 
as  stored  in  the  information  segment. 

Related  Functions 

• WinQueryMsgTime 

• WinStartTimer 

• WinStopTimer 

Example  Code 

This  example  uses  WinGetCurrentTime  to  return  the  current  time. 

Idefine  INCL_WINTIMER  /*  Window  Timer  Functions  */ 

linclude  <os2.h> 

HAB  hab;  /*  anchor-block  handle  */ 

ULONG  ulTime;  /*  current  time  */ 

ulTime  = WinGetCurrentTime(hab) ; 
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WinGetDIgMsg  - 
Get  Dialog  Message 


#define  INCL_WINDIALOGS  /*  Or  use  INCL_WIN  or  INCL_PM.  Also  in  COMMON  section  7 


BOOL  WinGetDIgMsg  (HWND  hwndDIg,  PQMSG  pqmsgmsg) 


This  function  obtains  a message  from  the  application’s  queue  associated  with  the  specified  dialog. 


Parameters 

hwndDIg  (HWND)  - input 
Dialog-window  handle. 

pqmsgmsg  (PQMSG)  - output 
Message  structure. 


Returns 

Continue  message  indicator: 

TRUE  Message  returned  is  not  a WMQUIT  message  and  the  dialog  has  not  been  dismissed. 

FALSE  Message  returned  is  a WM  QUIT  message  or  the  dialog  has  been  dismissed. 

Possible  returns  from  WinGetLastError 

PMERR  INVALID  HWND  An  invalid  window  handle  was  specified. 

Remarks 

This  function  enables  a language  that  cannot  support  window  procedures  to  provide  the  function  of  a 
modal  dialog.  The  application  creates  a modeless  dialog  by  the  use  of  the  WinCreateDIg  or  the 
WinLoadDIg  functions  and  then  issues  this  call  to  process  messages  only  associated  with  the  dialog. 

The  first  time  that  this  function  is  issued,  the  owner  of  the  window  specified  by  hwndDIg  is  disabled, 
thereby  preventing  input  into  windows  other  than  the  dialog.  The  owner  of  the  window  specified  by 
hwndDIg  is  enabled  when  the  WinDismissDIg  function  is  issued  either  by  the  application  or  by  the 
default  dialog  procedure. 

If  a WM  QUIT  is  encountered,  WinGetDIgMsg  itself  issues  a WinDismissDIg  function,  and  posts  the 
WM_QUIT  message  back  to  the  queue  so  that  the  application  main  loop  terminates  in  the  normal 
way. 
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WinGetDIgMsg  - 
Get  Dialog  Message 


Related  Functions 

• WinCreateDIg 

• WinDefDIgProc 

• WinDismissDIg 

• WinDIgBox 

• WinLoadDIg 

• WinProcessDIg 

• WinBroadcastMsg 

• WinCreateMsgQueue 

• WinDestroyMsgQueue 

• WinDispatchMsg 

• WinGetMsg 

• WinlnSendMsg 

• WinPeekMsg 

• WinPostMsg 

• WinPostQueueMsg 

• WinQueryMsgPos 

• WinQueryMsgTime 

• WinQueryQueuelnfo 

• WinQueryQueueStatus 

• WinRegisterllserDatatype 

• WinRegisterllserMsg 

• WinSendDIgltemMsg 

• WinSendMsg 

• WinSetClassMsglnterest 

• WinSetMsglnterest 

• WinSetMsgMode 

• WinSetSynchroMode 

• WinWaitMsg 

Related  Messages 

• WM_QUIT 
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WinGetDIgMsg  - 
Get  Dialog  Message 


Example  Code 

This  example  uses  WinGetDIgMsg  to  provide  a modal  dialog.  When  the  user  causes  an  open 
message  (application  defined  IDMOPEN),  the  dialog  is  loaded  and  displayed;  WinGetDIgMsg  then 
loops,  grabbing  messages  from  the  queue  and  calling  MyDIgRoutine  -the  dialog  procedure  which 
processes  the  messages-  with  the  appropriate  parameters.  When  the  dialog  issues  a WMQUIT, 
WinGetDIgMsg  returns  FALSE  and  the  loop  ends,  returning  control  to  owner  window. 


Idefine  INCL_WINDIALOGS  /*  Window  Dialog  Mgr  Functions  */ 

linclude  <os2.h> 


HWND 

hwnd; 

/*  owner  window 

*/ 

HWND 

hwndDl g ; 

/*  dialog  window 

*/ 

QMSG 

qmsg; 

/*  message 

*/ 

case 

IDM  OPEN: 

hwndDlg  = WinLoadDlg(HWND_DESKTOP,  /*  parent  is  desk  top  */ 
hwnd,  /*  owner  window  handle  */ 

NULL,  /*  modeless  dialog  */ 

OL,  /*  load  from  .EXE  */ 

DLG_ID,  /*  dialog  resource  id  */ 

NULL);  /*  no  dialog  parameters  */ 

/*  loop  and  process  dialog  messages  until  WM_QUIT,  calling 
dialog  procedure  for  each  message  */ 
while  (WinGetDIgMsg (hwndDlg,  &qmsg)) 

MyDlgRoutine(hwndDlg,  qmsg.msg,  qmsg.mpl,  qmsg.mp2); 
break; 


MRESULT  MyDl gRout i ne ( HWND  hwndDlg,  ULONG  usMsgid,  MPARAM  mpl, 
MPARAM  mp2) 

{ 

switch(usMsgid) 

{ 

/* 

. process  messages 
*/ 

default: 

return  (WinDefDlgProc( hwndDlg,  usMsgid,  mpl,  mp2)); 

} 
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WinGetErrorlnfo  - 
Get  Error  Information 


#define  INCL_WINERRORS  /*  Or  use  INCL_WIN  or  INCL_PM  */ 


PERRINFO  WinGetErrorlnfo  (HAB  hab) 


This  function  returns  detailed  error  information. 

Parameters 

hab  (HAB)  - input 

Anchor-block  handle. 


Returns 

Error  information. 

This  structure  contains  information  about  the  previous  error  code  for  the  current  thread: 

NULL  No  error  information  available 
Other  Error  information. 

Remarks 

This  function  allocates  a single  private  segment  to  contain  the  ERRINFO  structure.  All  the  pointers  to 
string  fields  within  the  ERRINFO  structure  are  offsets  to  memory  within  that  segment. 

The  memory  allocated  by  this  function  is  not  released  until  the  returned  pointer  is  passed  to  the 
WinFreeErrorlnfo  function. 

Related  Functions 

• WinFreeErrorlnfo 

• WinGetLastError 

Example  Code 

This  example  uses  WinGetErrorlnfo  to  obtain  detailed  error  information,  assigns  the  error  code,  and 
frees  the  error  block  with  WinFreeErrorlnfo. 


Idefine  INCL_WINERRORS  /*  Window  Error  Functions  */ 
finclude  <os2.h> 

BOOL  f Success;  /*  success  indicator  */ 
ERRORID  erridErrorCode;/*  last  error  id  code  */ 
PERRINFO  perriErrorlnfo;/*  error  info  structure  */. 
HAB  hab;  /*  anchor-block  handle  */ 


/*  obtain  error  block  */ 
perriErrorlnfo  = WinGetErrorlnfo(hab) ; 
erridErrorCode  = perriErrorInfo->idError; 

/*  free  error  block  */ 

fSuccess  = WinFreeErrorlnfo(perriErrorlnfo) ; 
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WinGetKeyState 
Get  Key  State 


#define  INCL_WININPUT  /*  Or  use  INCL_WIN  or  INCL_PM  7 


LONG  WinGetKeyState  (HWND  hwndDeskTop,  LONG  IVk) 


This  function  returns  the  state  of  the  key  at  the  time  that  the  last  message  obtained  from  the  queue 
was  posted. 

Parameters 

hwndDeskTop  (HWND)  - input 
Desktop-window  handle: 

HWND_DESKTOP  The  desktop-window  handle 

Other  Specified  desktop-window  handle. 

IVk  (LONG)  - input 
Virtual  key  value. 

Contains  the  virtual  key  value  in  the  low-order  byte,  and  zero  in  the  high-order  byte. 


Returns 

Key  state. 

This  value  is  the  OR  combination  of  the  following  bits: 

X'0001 ' The  key  has  been  pressed  an  odd  number  of  times  since  the  system  has  been 
started. 

X'8000'  The  key  is  down. 

Possible  returns  from  WinGetLastError 

PMERRJNVALID  HWND  An  invalid  window  handle  was  specified. 

Remarks 

See  also  the  WinGetPhysKeyState  function.  This  function  is  used  to  determine  whether  a virtual  key 
is  up,  down,  or  toggled. 

This  function  can  be  used  to  obtain  the  state  of  the  pointing  device  buttons  with  the  VK_BUTTON1, 
VK_BUTTON2,  and  VK_BUTTON3  virtual  key  codes. 


Related  Functions 

• WinEnablePhysinput 

• WinFocusChange 

• WinGetPhysKeyState 

• WinQueryFocus 

• WinSetFocus 

• WinSetKeyboardStateTable 
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WinGetKey State  - 
Get  Key  State 


Example  Code 

This  example  uses  WinGetKey  State  to  check  if  mouse  button  1 was  depressed  when  a WM_TIMER 
message  was  received.  A high  pitched  beep  is  emitted  if  it  was  depressed,  and  a low  pitched  beep  if 
it  was  not. 


fdefine  INCL_WININPUT  /*  Window  Input  Functions  */ 
fdefine  INCL_DOSPROCESS  /*  OS/2  Process  Functions  */ 
finclude  <os2.h> 

LONG  IKeyState;  /*  key  state  */ 
LONG  1 Vk ; /*  virtual  key  value  */ 


case  WM_TIMER: 

/*  get  key  state  of  mouse  button  1 */ 

1 Vk  = VK_BUTT0N1; 

IKeyState  = WinGetKeyState(HWND_DESKTOP,  lVk); 

/*  emit  high  pitched  beep  if  mouse  button  1 is  depressed 
when  timer  message  occurred;  otherwise,  emit  low  pitched 
beep  */ 

if  (lVk  & 0x8000) 

DosBeep(1000,10OL); 

else 

DosBeep(2OO,100L) ; 
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WinGetLastError  - 
Get  Last  Error 


#define  INCL_WINERRORS  /*  Or  use  INCL_WIN  or  INCL_PM  */ 


ERRORID  WinGetLastError  (HAB  hab) 


This  function  returns  the  error  state  set  by  the  failure  of  a Presentation  Manager  function. 

Parameters 

hab  (HAB)  - input 

Anchor-block  handle. 


Returns 

Last-error  state. 

Remarks 

Returns  the  last  nonzero  error  code,  and  sets  the  error  code  to  zero. 

The  current  error  state  is  reset  to  zero. 

In  multiple  thread  applications  where  there  are  multiple  anchor  blocks,  errors  are  stored  in  the 
anchor  block  created  by  the  Winlnitialize  function  of  the  thread  invoking  a call.  The  last  error  for  the 
process  and  thread  on  which  this  function  call  is  made  will  be  returned. 


Related  Functions 

• WinFreeErrorlnfo 

• WinGetErrorlnfo 

Example  Code 

This  example  uses  WinGetLastError  to  obtain  the  error  code  corresponding  to  the  last  nonzero  error 
for  the  specified  anchor  block.  If  only  the  error  code  is  required,  this  function  is  preferable  to  the 
WinGetErrorlnfo/WinFreeErrorlnfo  call  sequence. 

fdefine  INCL_WINERRORS  /*  Window  Error  Functions  */ 

linclude  <os2.h> 

ERRORID  erridErrorCode;/*  last  error  id  code  */ 

HAB  hab;  /*  anchor-block  handle  */ 

/*  get  last  nonzero  error  for  this  anchor  block  */ 
erridErrorCode  = WinGetLastError (hab) ; 
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WinGetMaxPosition  - 
Get  Maximum  Position 


#define  INCL_WINFRAMEMGR  /*  Or  use  INCL_WIN  or  INCL_PM  */ 


BOOL  WinGetMaxPosition  (HWND  hwnd,  PSWP  pSwp) 


The  WinGetMaxPosition  function  fills  an  SWP  structure  with  the  maximized-window  size  and  position. 

Parameters 

hwnd  (HWND)  - input 
Frame-window  handle. 

Identifies  the  window  whose  maximum  size  will  be  retrieved. 

pSwp  (PSWP)  - output 

Set  window  position  structure. 

Points  to  the  SWP  structure  that  retrieves  the  size  and  position  of  a maximized  window. 

The  SWP_SIZE  and  SWP_MOVE  indicators  are  set  in  this  parameter  on  return  from  this  call, 
implying  that  the  x,  y,  cx,  and  cy  parameters  have  been  initialized. 

Returns 

Success  indicator: 

TRUE  Successful  completion. 

FALSE  Error  occurred. 
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WinGetMaxPosition  - 
Get  Maximum  Position 


Example  Code 

This  example  uses  WinGetMaxPosition  to  determine  the  maximized  position  for  the  window  in 
response  to  a maximize  message  (WMMINMAXFRAME),  and  then  calls  WinSetWindowPos  to 
maximize  the  window  to  that  position. 


Idefine  INCL_WINFRAMEMGR  /*  Window  Frame  Functions  */ 
finclude  <os2.h> 

BOOL  fSuccess;  /*  Success  indicator  */ 
HWND  hwnd;  /*  window  handle  */ 
MPARAM  mpl;  /*  Parameter  1 (window  position)  */ 
PSWP  pSwp;  /*  Set  window  position  structure  */ 


case  WM_MINMAXFRAME: 

pSwp  = (PSWP)PVOIDFROMMP(mpl) ; 

switch(pSwp->fl) 

{ 

case  SWP_MAXIMIZE: 

fSuccess  = WinGetMaxPosition (hwnd,  pSwp); 

WinSetWindowPos (hwnd,  0L, 

pSwp->x,  /*  x pos  */ 

pSwp->y,  /*  y pos  */ 

pSwp->cx,  /*  x size  */ 

pSwp->cy,  /*  y size  */ 

SWP_MAXIMIZE) ; /*  flags  */ 

break; 

} 
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WinGetMinPosition  - 
Get  Minimum  Position 


#define  INCL_WINFRAMEMGR  /*  Or  use  INCL_WIN  or  INCL_PM  */ 


BOOL  WinGetMinPosition  (HWND  hwnd,  PSWP  pSwp,  PPOINTL  pptIPoInt) 


This  function  returns  the  position  to  which  a window  is  minimized. 


Parameters 

hwnd  (HWND)  - input 
Frame-window  handle. 

pSwp  (PSWP)  - output 

Set  window  position  structure. 

The  SWP_SIZE  and  SWP_MOVE  indicators  are  set  in  this  parameter  on  return  from  this  function, 
implying  that  the  x,  y,  cx,  and  cy  parameters  have  been  initialized. 

pptIPoInt  (PPOINTL)  - input 
Preferred  position: 

NULL  System  is  to  choose  the  position 

Other  System  is  to  choose  the  position  nearest  to  the  specified  point. 

Returns 

Success  indicator: 

TRUE  Successful  completion. 

The  WS_MINIMIZE  style  is  set  for  hwnd.  This  enables  the  system  to  determine  which 
other  frame  windows  are  minimized,  during  the  enumeration  process  performed  by 
this  function. 

Also,  the  window  words  QWS_XMINIMIZE  and  QWS_YMINIMIZE  for  hwnd  are 
initialized.  This  enables  the  system  to  ensure  that  no  windows  that  have  been,  or  are 
being,  minimized  use  the  same  position. 

FALSE  Error  occurred. 

Remarks 

This  function  chooses  the  position  for  a minimized  window.  It  enumerates  all  the  siblings  of  the 
specified  window  to  determine  the  first  available  position. 


Related  Functions 

• WinQueryActiveWindow 

• WinQueryWindowPos 

• WinSaveWindowPos 

• WinSetActiveWindow 

• WinSetMultWindowPos 

• WinSetWindowPos 
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WinGetMinPosition  - 
Get  Minimum  Position 


Example  Code 

This  example  uses  WinGetMinPosition  to  determine  the  minimized  position  for  the  window  in 
response  to  a minimize  message  (WM_MINMAXFRAME),  and  then  calls  WinSetWindowPos  to 
minimize  the  window  to  that  position. 


Idefine  INCL_WINFRAMEMGR  /*  Window  Frame  Functions  */ 
linclude  <os2.h> 

BOOL  fSuccess;  /*  Success  indicator  */ 
HWND  hwnd;  /*  window  handle  */ 
MPARAM  mpl;  /*  Parameter  1 (window  position)  */ 
PSWP  pSwp;  /*  Set  window  position  structure  */ 


case  WM_MINMAXFRAME: 

pSwp  = (PSWP)PVOIDFROMMP(mpl) ; 

switch(pSwp->fl) 

{ 

case  SWP_MINIMIZE: 

fSuccess  = WinGetMinPosition(hwnd,  pSwp,  NULL); 

WinSetWindowPos(hwnd,  0L, 

pSwp->x,  /*  x pos  */ 

pSwp->y,  /*  y pos  */ 

pSwp->cx,  /*  x size  */ 

pSwp->cy,  /*  y size  */ 

SWP_MINIMIZE) ; /*  flags  */ 

break; 

} 
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WinGetMsg  - 
Get  Message 


#define  INCL.WINMESSAGEMGR  /*  Or  use  INCL_WIN  or  INCL_PM.  Also  in  COMMON  section  */ 


BOOL  WinGetMsg  (HAB  hab,  PQMSG  pqmsgmsg,  HWND  hwndFllter,  ULONG  ulFIrst, 
ULONG  u I Last) 


This  function  gets,  waiting  if  necessary,  a message  from  the  thread’s  message  queue  and  returns 
when  a message  conforming  to  the  filtering  criteria  is  available. 


Parameters 

hab  (HAB)  - input 

Anchor-block  handle. 

pqmsgmsg  (PQMSG)  - output 
Message  structure. 

hwndFllter  (HWND)  - input 
Window  filter. 

ulFIrst  (ULONG)  - input 
First  message  identity. 

ulLast  (ULONG)  - input 
Last  message  identity. 


Returns 

Continue  message  indicator: 

TRUE  Message  returned  is  not  a WM  QUIT  message 
FALSE  Message  returned  is  a WM_QUIT  message. 

Possible  returns  from  WinGetLastError 

PMERR  INVALID  HWND  An  invalid  window  handle  was  specified. 

Remarks 

If  system  or  queue  hooks  are  installed,  they  are  called  before  this  function  returns. 

f Result  is  generally  used  to  determine  when  to  terminate  the  application’s  main  loop  and  exit  the 
program. 

hwndFilter  constrains  the  returned  message  to  be  for  a specific  window  or  its  children.  When 
hwndFilter  is  null,  the  returned  message  can  be  for  any  window.  The  message  identity  is  restricted 
to  the  range  of  message  identities  specified  by  ulFirst  and  ulLast  inclusive.  When  ulFirst  and  ulLast 
are  both  zero,  any  message  satisfies  the  range  constraint.  When  ulFirst  is  greater  than  ulLast, 
messages  except  those  whose  identities  lie  between  ulFirst  and  ulLast  are  eligible  to  be  returned. 
Messages  that  do  not  conform  to  the  filtering  criteria  remain  in  the  queue. 

When  hwndFilter  is  null,  and  ulFirst  and  ulLast  are  both  zero,  all  messages  are  returned  in  the  order 
that  they  were  posted  to  the  queue. 

By  using  filtering,  messages  can  be  processed  in  an  order  that  is  different  from  the  one  in  the  queue. 
Filtering  is  used  in  situations  where  applications  receive  messages  of  a particular  type,  rather  than 
having  to  deal  with  other  types  of  message  at  an  inconvenient  point  in  the  logic  of  the  application. 

For  example,  when  a “mouse  down”  message  is  received,  filtering  can  be  used  to  wait  for  the 
“mouse  up”  message  without  having  to  be  concerned  with  receiving  other  messages. 
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WinGetMsg 
Get  Message 


These  constants  can  also  be  used  when  filtering  messages: 


WM_MOUSEFIRST 

WMMOUSELAST 

WMBUTTONCLICKFIRST 

WMBUTTONCLICKLAST 

WM_DDE_FIRST 

WMDDELAST 


Lowest  value  pointing  device  message 
Highest  value  pointing  device  message 
Lowest  value  pointing  device  button  click  message 
Highest  value  pointing  device  button  click  message 
Lowest  value  DDE  message 
Highest  value  DDE  message. 


Great  care  must  be  taken  if  filtering  is  used,  to  ensure  that  a message  that  satisfies  the  specification 
of  the  filtering  parameters  can  occur,  otherwise  this  function  cannot  complete.  For  example,  calling 
this  function  with  ulFirst  and  ulLast  equal  to  WMCHAR  and  with  hwndFilter  set  to  a window  handle 
that  does  not  have  the  input  focus,  prevents  this  function  from  returning. 


Keystrokes  are  passed  to  the  WinTranslateAccel  call,  which  implies  that  accelerator  keys  are 
translated  into  WM_COMMAND  or  WM_SYSCOMMAND  messages,  and  so  are  not  seen  as  WM  CHAR 
messages  by  the  application. 

Note:  An  application  must  be  prepared  to  receive  messages  other  than  those  documented  in  this 

publication.  All  messages  that  an  application  does  not  want  to  handle  should  be  dispatched  to 
the  appropriate  window  procedure  using  the  WinDispatchMsg  function. 


Related  Functions 

• WinCancelShutdown 

• WinBroadcastMsg 

• WinCreateMsgQueue 

• WinDestroyMsgQueue 

• WinDispatchMsg 

• WinGetDIgMsg 

• WinlnSendMsg 

• WinPeekMsg 

• WinPostMsg 

• WinPostQueueMsg 

• WinQueryMsgPos 

• WinQueryMsgTime 

• WinQueryQueuelnfo 

• WinQueryQueueStatus 

• WinRegisterUserDatatype 

• WinRegisterUserMsg 

• WinSendDIgltemMsg 

• WinSendMsg 

• WinSetClassMsglnterest 

• WinSetMsglnterest 

• WinSetMsgMode 

• WinSetSynchroMode 

• WinWaitMsg 

Related  Messages 

• WM_CHAR 

• WM_CHAR 

• WM_QUIT 

• WM_SYSCOM  M AND 
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WinGetMsg  - 
Get  Message 


Example  Code 

This  example  uses  WinGetMsg  to  continually  loop  and  retrieve  messages  from  the  message  queue 
until  a WM  QUIT  message  occurs. 


fdefine  INCL_WINMESSAGEMGR  /*  Window  Message  Functions  */ 
fdefine  INCL_WINWINDOWMGR  /*  Window  Manager  Functions  */ 
finclude  <os2.h> 


HAB 

hab; 

/*  anchor-block  handle 

*/ 

HMQ 

hmq; 

/*  message  queue  handle 

*/ 

QMSG 

qmsg; 

/*  message 

*/ 

hab  = Winlnitialize(O);  /*  initialize  PM  */ 

hmq  = WinCreateMsgQueue(hab,  0);  /*  create  default  size  queue  */ 

/* 

. initialize  windows 


*/ 

/*  get  and  dispatch  messages  from  queue  */ 
while  (WinGetMsg(hab,  &qmsg,  0,  0,  0)) 
WinDispatchMsg(hab,  &qmsg); 
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WinGetNextWindow 
Get  Next  Window 


#define  INCL_WINWINDOWMGR  /*  Or  use  INCL_WIN  or  INCL_PM  */ 


HWND  WinGetNextWindow  (HENUM  henum) 


This  function  gets  the  window  handle  of  the  next  window  in  a specified  enumeration  list. 

Parameters 

henum  (HENUM)  - input 
Enumeration  handle. 

Returned  by  previous  call  to  the  WinBeginEnumWindows  call. 


Returns 

Next  window  handle  in  enumeration  list: 

NULLHANDLE  Error  occurred,  henum  was  invalid,  or  all  the  windows  have  been  enumerated. 
Other  Next  window  handle. 

Possible  returns  from  WinGetLastError 

PMERRINVALIDHENUM  An  invalid  enumeration  handle  was  specified. 

Remarks 

Enumeration  starts  with  the  topmost  child  window  and  then  proceeds  downward  through  the 
enumeration  list,  in  z-order  at  the  time  the  WinBeginEnumWindows  was  issued,  until  all  the  windows 
have  been  enumerated.  At  this  point,  the  call  returns  NULLHANDLE.  The  enumeration  then  wraps 
and  the  handle  of  the  topmost  child  window  is  returned  on  the  next  call.  This  function  does  not  lock 
windows.  Window  locking  is  not  required  in  OS/2  release  1.2  and  above. 


Related  Functions 

• WinBeginEnumWindows 

• WinEndEnumWindows 

• WinEnumDIgltem 

• WinlsChild 

• WinMultWindowFromIDs 

• WinQueryWindow 

• WinSetOwner 

• WinSetParent 
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Get  Next  Window 


Example  Code 

This  example  moves  through  all  the  child  windows  in  a enumeration  list,  using  an  enumeration 
handle  provided  by  WinBeginEnumWindows;  for  each  child  window,  the  class  name  is  queried  and 
placed  in  a buffer. 


Idefine  INCL_WINWINDOWMGR  /*  Window  Manager  Functions  */ 

linclude  <os2.h> 

HWND  hwndParent;  /*  Handle  of  the  window  whose  child  windows 

are  to  be  enumerated  */ 

HWND  hwndNext;  /*  current  enumeration  handle  */ 

HENUM  henum;  /*  enumeration  handle  */ 

BOOL  fSuccess;  /*  success  indicator  */ 

SHORT  sRetLen;  /*  returned  string  length  */ 

SHORT  sLength  = 10;  /*  string  buffer  length  */ 

char  pchBuffer[10] ; /*  string  buffer  */ 


hwndParent  = HWND_DESKTOP; 

henum  = Wi nBeginEnumWindows (hwndParent) ; 

while  ((hwndNext  = WinGetNextWindow(henum))  !=  NULLHANDLE) 
sRetLen  = WinQueryClassName(hwndNext,  sLength,  pchBuffer); 

fSuccess  = WinEndEnumWindows  (henum); 
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WinGetPhysKeyState 
Get  Physical  Key  State 


#define  INCL_WININPUT  /*  Or  use  INCL_WIN  or  INCL_PM  V 


This  function  returns  the  physical  key  state. 

Parameters 

hwndDeskTop  (HWND)  - input 
Desktop-window  handle: 

HWND_DESKTOP  The  desktop-window  handle 

Other  Specified  desktop-window  handle. 

IScancode  (LONG)  - input 
Hardware  scan  code. 

Contains  the  scan  code  value  in  the  low-order  byte,  and  zero  in  the  high-order  byte. 

Returns 

Key  state: 

This  value  is  the  OR  combination  of  the  following  bits: 

X'0001 1 The  key  has  been  pressed  an  odd  number  of  times  since  the  system  has  been 
started. 

X'0002'  The  key  has  been  pressed  since  the  last  time  this  function  was  issued,  or  since  the 
system  has  been  started  if  this  is  the  first  time  the  call  has  been  issued. 

X'8000'  The  key  is  down. 

Possible  returns  from  WinGetLastError 

PMERRINVALIDHWND  An  invalid  window  handle  was  specified. 

Remarks 

This  function  returns  information  about  the  asynchronous  (interrupt  level)  state  of  the  virtual  key 
indicated  by  the  IScancode  parameter. 

This  function  returns  the  physical  state  of  the  key;  it  is  not  synchronized  to  the  processing  of  input 
(see  the  WinGetKeyState  function). 

Related  Functions 

• WinEnablePhysinput 

• WinFocusChange 

• WinGetKeyState 

• WinQueryFocus 

• WinSetFocus 

• WinSetKeyboardStateTable 
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WinGetPhysKeyState  - 
Get  Physical  Key  State 


Example  Code 

This  example  uses  WinGetPhysKeyState  to  check  the  current  state  of  the  caps  lock  key;  if  it  is 
depressed,  a high  pitch  beep  is  emitted,  while  a low  pitch  beep  is  emitted  if  it  is  not  depressed. 


fdefine  INCL_WININPUT  /*  Window  Input  Functions  */ 
fdefine  INCL_DOSPROCESS  /*  OS/2  Process  Functions  */ 
finclude  <os2.h> 

LONG  IKeyState;  /*  key  state  */ 
LONG  lScancode;  /*  scan  code  value  */ 


/*  get  physical  key  state  for  caps  lock  key  */ 
lScancode  = VK_CAPSLOCK; 

IKeyState  = WinGetPhysKeyState(HWND_DESKTOP,  lScancode); 

/*  emit  high  pitched  beep  if  caps  lock  is  currently  depressed; 

otherwise,  emit  low  pitched  beep  */ 
if  (lScancode  & 0x8000) 

DosBeep(1000,100L) ; 
else 

DosBeep(200,100L) ; 
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WinGetPS  - 

Get  Presentation  Space 


#define  INCL_WINWINDOWMGR  /*  Or  use  INCL_WIN  or  INCL_PM.  Also  in  COMMON  section  7 


HPS  WinGetPS  (HWND  hwnd) 


This  function  gets  a cache  presentation  space. 


Parameters 

hwnd  (HWND)  - input 

Handle  of  window  for  which  the  presentation  space  is  required: 

HWND_DESKTOP  The  desktop-window  handle;  a presentation  space  for  the  whole  of  the 
desktop  window  is  returned 

Other  Handle  of  window  for  which  the  presentation  space  is  required. 

Returns 

Presentation-space  handle  that  can  be  used  for  drawing  in  the  window. 

Possible  returns  from  WinGetLastError 

PMERR  INVALID  HWND  An  invalid  window  handle  was  specified. 


Remarks 

The  presentation  space  created  by  this  function  is  a cache  “micro  presentation  space”  present  in  the 
system.  This  can  be  used  for  simple  drawing  operations  that  do  not  depend  on  long-term  data  being 
stored  in  the  presentation  space. 


The  initial  state  of  the  presentation  space  is  the  same  as  that  of  a presentation  space  created  using 
the  GpiCreatePS  function.  The  color  table  is  in  default  color  index  mode.  The  visible  region 
associated  with  hps  depends  upon  the  window  and  class  styles  of  hwnd: 


Style 

WS_CLIPCHILDREN 

WSCLIPSIBLINGS 

CSPARENTCLIP 


Visible  region  of  presentation  space 

All  child  windows  of  the  window  are  excluded. 

All  the  sibling  windows  of  hwnd  are  excluded. 

Is  the  same  as  that  of  the  parent  window  of  the  window. 

The  presentation  space  origin  is  established  normally,  that  is,  relative  to  the 
lower  left  of  the  window  itself,  not  its  parent. 

This  style  optimizes  the  use  of  the  presentation  space  cache  by  minimizing 
the  calculation  of  the  visible  region  for  child  windows. 


Any  presentation  space  created  by  WinGetPS  must  be  released  by  calling  WinReleasePS.  This 
should  be  done  before  the  application  terminates. 
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WinGetPS  - 
Get  Presentation  Space 


Related  Functions 

• WinBeginPaint 

• WinEnableWindowllpdate 

• WinEndPaint 

• WinExcludellpdateRegion 

• WinGetClipPS 

• WinGetScreenPS 

• WinlnvalidateRect 

• WinlnvalidateRegion 

• WinlsWindowShowing 

• WinlsWindowVisible 

• WinLockVisRegions 

• WinOpenWindowDC 

• WinQueryllpdateRect 

• WinQueryllpdateRegion 

• WinRealizePalette 

• WinReleasePS 

• WinShowWindow 

• WinllpdateWindow 

• WinValidateRect 

• WinValidateRegion 


Example  Code 

This  example  processes  an  application-defined  message  (IDM_FILL).  It  calls  WinGetPS  to  get  a 
presentation  space  to  the  entire  window.  It  gets  the  dimensions  of  the  current  window,  fills  the 
window,  and  calls  WinReleasePS  to  release  the  presentation  space. 


fdefine  INCL_WINWINDOWMGR  /*  Window  Manager  Functions  */ 

finclude  <os2.h> 

HWND  hwnd;  /*  parent  window  */ 

RECTL  rcl;  /*  update  region  */ 

HPS  hps;  /*  presentation-space  handle  */ 

case  IDM_FILL: 

hps  = WinGetPS (hwnd);  /*  get  presentation  space  for  */ 

/*  the  entire  window  */ 

WinQueryWindowRect(hwnd,  &rcl ) ; /*  get  window  dimensions  */ 
Wi nFi 1 1 Rect ( hps , &rcl , CLR_WHITE);  /*  clear  entire  window  */ 


WinReleasePS(hps) ; 
return  0L; 


/*  release  the  presentation  */ 
/*  space  */ 
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WinGetScreenPS  - 

Get  Screen  Presentation  Space 


#define  INCL_WINWINDOWMGR  /*  Or  use  INCL.WIN  or  INCL_PM  */ 


HPS  WinGetScreenPS  (HWND  hwndDeskTop) 


This  function  returns  a presentation  space  that  can  be  used  for  drawing  anywhere  on  the  screen. 


Parameters 

hwndDeskTop  (HWND)  - input 
Desktop-window  handle: 

HWND_DESKTOP  The  desktop-window  handle 
Other  Specified  desktop-window  handle. 

Returns 

Presentation-space  handle 

A micro  presentation  space  that  can  be  used  for  drawing  over  the  entire  desktop  window  (the 
whole  screen): 

NULLHANDLE  hwndDeskTop  is  not  HWND  DESKTOP  or  a desktop  window  handle  obtained 
from  the  WinQueryDesktopWindow  function. 

Other  Presentation  space  handle. 

Possible  returns  from  WinGetLastError 

PMERR  INVALID  HWND  An  invalid  window  handle  was  specified. 

Remarks 

Take  great  care  when  using  this  function.  The  returned  presentation  space  is  not  clipped  to  any  of 
the  other  windows  present  on  the  screen.  Thus  it  is  possible  to  draw  in  regions  belonging  to 
windows  of  other  threads  and  processes. 

The  WinLockWindowllpdate  function  should  be  used  to  avoid  simultaneous  updates  to  the  same  part 
of  the  screen.  This  does  not  cause  the  presentation  space  returned  by  this  function  to  become 
clipped  in  any  way.  Care  of  the  appearance  of  windows  of  other  threads  is  still  the  responsibility  of 
the  user  of  the  screen  presentation  space. 

When  the  application  finishes  using  the  screen  presentation  space,  it  should  be  destroyed  using  the 
WinReleasePS  call. 
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Related  Functions 

• WinBeginPaint 

• WinEnableWindowUpdate 

• WinEndPaint 

• WinExcludeUpdateRegion 

• WinGetClipPS 

• WinGetPS 

• WinlnvalidateRect 

• WinlnvalidateRegion 

• WinlsWindowShowing 

• WinlsWindowVisible 

• WinLockVisRegions 

• WinOpenWindowDC 

• WinQueryllpdateRect 

• WinQueryllpdateRegion 

• WinRealizePalette 

• WinReleasePS 

• WinShowWindow 

• WinllpdateWindow 

• WinValidateRect 

• WinValidateRegion 

Example  Code 

This  example  processes  an  application-defined  message  (IDM_FILL).  It  calls  WinGetScreenPS  to  get 
a presentation  space  for  the  entire  desktop  window,  gets  the  dimensions  of  the  current  window,  fills 
the  window,  and  calls  WinReleasePS  to  release  the  presentation  space. 

fdefine  INCL_WINWINDOWMGR  /*  Window  Manager  Functions  */ 

linclude  <os2.h> 

HWNO  hwnd;  /*  parent  window  */ 

RECTL  rcl;  /*  update  region  */ 

HPS  hps;  /*  presentation-space  handle  */ 

case  I DM_F ILL: 

/*  get  presentation  space  for  the  entire  desktop  */ 
hps  = WinGetScreenPS(HWND_DESKTOP) ; 

WinQueryWindowRect(hwnd,  &rcl);  /*  get  window  dimensions  */ 

WinFillRect(hps,  &rcl,  CLR_WHITE);  /*  clear  entire  window  */ 

WinReleasePS(hps) ; /*  release  the  presentation  space  * 

return  0L; 
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WinGetSysBitmap  - 
Get  System  Bit  Map 


#define  INCL_WINPOINTERS  /*  Or  use  INCL_WIN  or  INCL_PM  7 


HBITMAP  WinGetSysBitmap  (HWNO  hwndDeskTop,  ULONG  ullndex) 


This  function  returns  a handle  to  one  of  the  standard  bit  maps  provided  by  the  system. 


Parameters 

hwndDeskTop  (HWND)  - input 
Desktop-window  handle: 

HWND_DESKTOP  The  desktop-window  handle 

Other  Specified  desktop-window  handle. 

ullndex  (ULONG)  - input 

System  bit-map  index  value: 


SBMP_SYSMENU 

SBMPSYSMENUDEP 

SBMPSBUPARROW 

SBMPSBUPARROWDEP 

SBMPSBUPARROWDIS 

SBMPSBDNARROW 

SBMPSBDNARROWDEP 

SBMPSBDNARROWDIS 

SBMP  SBRGARROW 

SBMPSBRGARROWDEP 

SBMPSBRGARROWDIS 

SBMPSBLFARROW 

SBMPSBLFARROWDEP 

SBMPSBLFARROWDIS 

SBMPMENUCHECK 

SBMPMENU  ATTACHED 

SBMPCHECKBOXES 

SBMPCOMBODOWN 

SBMPBTNCORNERS 

SBMPMINBUTTON 

SBMPMINBUTTONDEP 

SBMPMAXBUTTON 

SBMPMAXBUTTONDEP 

SBMPRESTOREBUTTON 

SBMPRESTOREBUTTONDEP 

SBMPCHILDSYSMENU 


System  menu 

System  menu  in  depressed  state 

Scroll  bar  up  arrow 

Scroll  bar  up  arrow  in  depressed  state 

Scroll  bar  up  arrow  in  disabled  state 

Scroll  bar  down  arrow 

Scroll  bar  down  arrow  in  depressed  state 

Scroll  bar  down  arrow  in  disabled  state 

Scroll  bar  right  arrow 

Scroll  bar  right  arrow  in  depressed  state 

Scroll  bar  right  arrow  in  disabled  state 

Scroll  bar  left  arrow 

Scroll  bar  left  arrow  in  depressed  state 

Scroll  bar  left  arrow  in  disabled  state 

Menu  check  mark 

Cascading  menu  mark 

Check  box  or  radio  button  check  marks 

Combobox  down  arrow 

Pushbutton  corners 

Minimize  button 

Minimize  button  in  depressed  state 
Maximize  button 

Maximize  button  in  depressed  state 
Restore  button 

Restore  button  in  depressed  state 
System  menu  for  child  windows 
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SBMP_CHILDSYSMENUDEP 

SBMPDRIVE 

SBMPFILE 

SBMPFOLDER 

SBMPTREEPLUS 

SBMPTREEMINUS 

SBMPCLOSEBUTTON 

SBMPCLOSEBUTTONDEP 

SBMPPROGRAM 

SBMPSIZEBOX 


System  menu  for  child  windows  in  depressed  state 

Drive 

File 

Folder 

Used  by  the  file  system  to  indicate  that  an  entry  in  the  directory 
can  be  expanded. 

Used  by  the  file  system  to  indicate  that  an  entry  in  the  directory 
can  be  collapsed. 

Hide  button 

Hide  button  in  depressed  state 

Used  by  the  file  system  to  mark  .EXE  and  .COM  files. 

Used  by  some  applications  to  display  a sizebox  in  the 
bottom-right  corner  of  a frame  window. 


Returns 

System  bit-map  handle. 

NULLHANDLE  Error  occurred 
Other  System  bit-map  handle. 

Possible  returns  from  WinGetLastError 

PMERR  INVALID  HWND  An  invalid  window  handle  was  specified. 

PMERR_PARAMETER_OUT_OF_RANGE  The  value  of  a parameter  was  not  within  the  defined  valid 

range  for  that  parameter. 

PMERR_RESOURCE_NOT_FOUND  The  specified  resource  identity  could  not  be  found. 


Remarks 

The  bit  map  returned  can  be  used  for  any  of  the  normal  bit-map  operations.  This  function  provides  a 
new  copy  of  the  system  bit  map  each  time  it  is  called.  The  application  should  release  any  bit  maps  it 
gets  with  this  function  by  using  the  GpiDeleteBitmap  function. 


Related  Functions 

• WinDrawBitmap 

• WinDrawBorder 

• WinDrawPointer 

• WinDrawText 

• WinFillRect 

• WinlnvertRect 

• WinQueryPresParam 

• WinRemovePresParam 

• WinScrollWindow 

• WinSetPresParam 
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WinGetSysBitmap  - 
Get  System  Bit  Map 


Example  Code 

This  example  uses  WinGetSysBitmap  to  retrieve  the  system  defined  handle  for  the  menu  check  mark 
bit  map  during  the  window  creation  phase.  The  bit-map  handle  is  then  later  used  to  draw  the  check 
mark  in  response  to  user  selection  of  a menu  item. 


*/ 

*/ 

*/ 

*/ 


*/ 
*/ 
*/ 
*/ 
*/ 
*/ 
*/ 

case  WM_CREATE: 

/*  obtain  check  mark  bit-map  handle  */ 

hbmCheck  = WinGetSysBitmap(HWND_DESKTOP,  SBMP_MENUCHECK) ; 

case  WM_MENUSELECT : 

usltemld  = SHORTlFROMMP(mpl) ; 
hwndMenu  = HWNDFR0MMP(mp2) ; 

/*  get  rectangle  of  selected  item  */ 

Wi nSendMsg ( hwndMenu , 

MMQUERYITEMRECT, 

MPFR0M2SH0RT ( us  I teml d , TRUE), 

MPFROMP(&rclItem)); 


# define  INCL_WINWINDOWMGR 
fdefine  INCL_WINPOINTERS 
fdefine  INCL_WINMESSAGEMGR 
fdefine  INCLJ/INMENUS 
finclude  <os2.h> 


/*  Window  Manager  Functions 
/*  Window  Pointer  Functions 
/*  Window  Message  Functions 
/*  Window  Menu  Functions 


HPS  hps; 

HBITMAP  hbmCheck; 


HWND 

USHORT 

MPARAM 

MPARAM 

RECTL 


hwndMenu; 

usltemld; 

mpl; 

mp2; 

rcl Item; 


/* 

/* 

/* 

/* 

/* 

/* 

/* 


presentation-space  handle 
check  mark  bit-map  handle 
menu  handle 
menu  item  id 

Parameter  1 (menu  item  id) 
Parameter  2 (menu  handle) 
item  border  rectangle 


/*  draw  the  check  mark  in  the  lower  left  corner  of  item's 
rectangle  */ 
if  (hbmCheck  !=  NULL) 

{ 

WinOrawBitmap(hps, 

hbmCheck,  /*  check  mark  */ 

NULL,  /*  draw  whole  bit  map  */ 

(PPOINTL)&rcl Item,/*  bit-map  destination  */ 
0L,  /*  ignored  since  color  */ 

0L,  /*  bit  map  */ 

DBM_NORMAL);  /*  draw  normal  size  */ 

} 
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WinlnflateRect  - 
Inflate  Rectangle 


#define  INCL_WINRECTANGLES  /*  Or  use  INCL_WIN  or  INCL_PM  */ 


BOOL  WinlnflateRect  (HAB  hab,  PRECTL  prclrect,  LONG  lex,  LONG  Icy) 


This  function  expands  a rectangle. 


Parameters 

hab  (HAB)  - input 

Anchor-block  handle. 

prclrect  (PRECTL)  - input/output 
Rectangle  to  be  expanded. 

Note:  The  value  of  each  field  in  this  structure  must  be  in  the  range  —32  768  through  32  767.  The 
datatype  WRECT  can  also  be  used,  if  supported  by  the  language. 

lex  (LONG)  - input 

Horizontal  expansion. 

Icy  (LONG)  - input 
Vertical  expansion. 


Returns 

Success  indicator: 

TRUE  Successful  completion 
FALSE  Error  occurred. 

Remarks 

This  function  adjusts  the  size  of  the  rectangle  by  applying  the  lex  parameter  horizontally  at  both 
vertical  edges  and  the  Icy  parameter  vertically  at  both  horizontal  edges. 

The  lex  parameter  is  subtracted  from  the  left  and  added  to  the  right  of  the  rectangle,  and  the  Icy 
parameter  is  subtracted  from  the  bottom  and  added  to  the  top  of  the  rectangle. 

If  the  values  of  the  lex  and  Icy  parameters  are  both  positive,  the  rectangle  is  enlarged  and  surrounds 
the  original  rectangle.  Conversely,  if  both  these  values  are  negative,  the  rectangle  is  reduced  in  size 
and  is  inset  with  respect  to  the  original  rectangle. 


Related  Functions 

• WinCopyRect 

• WinEqualRect 

• WinFillRect 

• WinlntersectRect 

• WinlsRectEmpty 

• WinOffsetRect 

• WinPtlnRect 

• WinSetRect 

• WinSetRectEmpty 

• WinSubtractRect 

• WinUnionRect 
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WinlnflateRect  - 
Inflate  Rectangle 

Example  Code 

This  example  doubles  the  size  of  a rectangle  if  the  mouse  is  double  clicked  (WMBUTTON1DBLCLK) 
within  the  rectangle  (WinPtlnRect). 

fdefine  INCL_WINRECTANGLES  /*  Window  Rectangle  Functions  */ 
linclude  <os2.h> 


BOOL  f Success;  /*  success  indicator  */ 
HAB  hab;  /*  anchor-block  handle  */ 
RECTL  prcl Recti  = {0,0,100,100};  /*  rectangle  */ 
LONG  lex  = 100;  /*  Horizontal  expansion  */ 
LONG  Icy  = 100;  /*  Vertical  expansion  */ 
POINTL  ptl;  /*  current  mouse  position  */ 
MPARAM  mpl;  /*  Parameter  1 (x,y)  point  value  */ 


case  WM  BUTT0N1DBLCLK: 

ptT.x  = (LONG)  SHORTlFROMMP(mpl) ; 
ptl .y  = (LONG)  SH0RT2FR0MMP(mpl) ; 

if  (WinPtInRect(hab,  SprclRectl,  &ptl ) ) 

fSuccess  = WinInflateRect(hab,  &prclRectl,  lex,  Icy); 


8-198  PM  Programming  Reference 


Winlnitialize  - 
Initialize 


#define  INCL_WINWINDOWMGR  /*  Or  use  INCL_WIN  or  INCL_PM.  Also  in  COMMON  section  7 


HAB  Winlnitialize  (ULONG  flOptlons) 


This  function  initializes  the  PM  facilities  for  use  by  an  application. 


Parameters 

flOptlons  (ULONG)  - input 
Initialization  options: 

0 The  initial  state  for  newly  created  windows  is  that  all  messages  for  the  window  are  available 
for  processing  by  the  application. 

This  is  the  only  option  available  in  PM. 


Returns 

Anchor-block  handle: 

NULLHANDLE  An  error  occurred. 

Other  Anchor-block  handle. 

Remarks 

This  must  be  the  first  PM  call  issued  by  any  application  thread  using  Presentation  Manager  facilities. 
It  returns  hab,  which  is  NULL  if  the  initialization  is  not  successful. 

The  operating  system  does  not  generally  use  the  information  supplied  by  the  hab  parameter  to  its 
calls;  instead,  it  deduces  it  from  the  identity  of  the  thread  that  is  making  the  call.  Thus  an  OS/2 
application  is  not  required  to  supply  any  particular  value  as  the  hab  parameter.  However,  in  order  to 
be  portable  to  other  environments,  an  application  must  provide  the  hab,  that  is  returned  by  the 
Winlnitialize  function  of  the  thread,  to  any  OS/2  function  that  requires  it. 

f /Options  determines  the  initial  state  of  message  processing  with  respect  to  a created  window. 


Related  Functions 

• WinCancelShutdown 

• WinCreateMsgQueue 

• WinTerminate 


Chapter  8.  Window  Functions 


8-199 


Winlnitialize  - 
Initialize 

Example  Code 

This  example  uses  Winlnitialize  to  obtain  an  anchor  block  and  initialize  Presentation  Manager. 


fdefine  INCL_WINMESSAGEMGR  /*  Window  Message  Functions  */ 
fdefine  INCL_WINWINDOWMGR  /*  Window  Manager  Functions  */ 
finclude  <os2.h> 


HAB 

hab; 

/*  anchor-block  handle 

*/ 

HMQ 

hmq; 

/*  message  queue  handle 

*/ 

QMSG 

qmsg; 

/*  message 

*/ 

hab  = Winlnitialize(O) ; /*  initialize  PM  */ 

hmq  = WinCreateMsgQueue(hab,  0);  /*  create  default  size  queue  */ 
/* 

. initialize  windows 


*/ 

/*  get  and  dispatch  messages  from  queue  */ 
while  (WinGetMsg(hab,  &qmsg,  0,  0,  0)) 
WinDispatchMsg(hab,  &qmsg); 
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WinlnSendMsg  - 
In  Send  Message 


#define  INCL_WINMESSAGEMGR  /*  Or  use  INCL_WIN  or  INCL_PM  */ 


BOOL  WinlnSendMsg  (HAB  hab) 


This  function  determines  whether  the  current  thread  is  processing  a message  sent  by  another 
thread. 

Parameters 

hab  (HAB)  - input 

Anchor-block  handle. 


Returns 

Message-processing  indicator: 

TRUE  Current  thread  is  processing  a message  sent  by  another  thread 
FALSE  Current  thread  is  not  processing  a message,  or  an  error  occurred. 

Remarks 

If  the  message  is  from  another  thread  this  function  determines  whether  or  not  the  message  was 
initiated  by  the  active  thread.  The  ‘active  thread’  is  the  thread  associated  with  the  current  active 
window.  (See  also  the  WinlsThreadActive  function.) 

Typically  this  function  is  used  by  applications  to  determine  howto  proceed  with  errors  when  the 
window  processing  the  message  is  not  the  active  window.  For  example,  if  the  active  window  uses 
the  WinSendMsg  function  to  send  a request  for  information  to  another  window,  the  other  window 
cannot  become  active  until  it  returns  control  from  the  WinSendMsg  function.  The  only  methods  an 
inactive  window  has  to  inform  the  user  of  an  error  are  to  create  a message  box  (see 
WinMessageBox),  or  to  flash  a window  (see  WinFlashWindow). 

This  function  can  be  used  to  tell  if  a function  is  being  called  recursively. 
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WinlnSendMsg  - 
In  Send  Message 


Related  Functions 

• WinBroadcastMsg 

• WinCreateMsgQueue 

• WinDestroyMsgQueue 

• WinDispatchMsg 

• WinGetDIgMsg 

• WinGetMsg 

• WinPeekMsg 

• WinPostMsg 

• WinPostQueueMsg 

• WinQueryMsgPos 

• WinQueryMsgTime 

• WinQueryQueuelnfo 

• WinQueryQueueStatus 

• WinRegisterUserDatatype 

• WinRegisterllserMsg 

• WinSendDIgltemMsg 

• WinSendMsg 

• WinSetClassMsglnterest 

• WinSetMsglnterest 

• WinSetMsgMode 

• WinSetSynchroMode 

• WinWaitMsg 


Example  Code 

This  example  determines,  during  a WMERROR  message,  if  the  current  thread  is  processing  a 
message  sent  by  another  thread  using  WinlnSendMsg;  if  so,  a message  box  is  generated  with  the 
error  information  to  alert  the  active  window  that  originally  sent  the  message. 


Idefine  INCL_WINMESSAGEMGR  /*  Window  Message  Functions  */ 
Idefine  INCL_WINDIALOGS  /*  Window  Dialog  Mgr  Functions  */ 
#include  <os2.h> 

HAB  hab;  /*  anchor-block  handle  */ 
BOOL  f Success;  /*  Success  indicator  */ 
MPARAM  mpl;  /*  Parameter  1 */ 
USHORT  errorcode;  /*  error  code  */ 
CHAR  szMsg[10O];  /*  message  text  */ 
HWND  hwnd;  /*  handle  of  window  with  error  msg  */ 


case  WM_ERR0R: 

/*  get  error  code  */ 
errorcode  = SHORTlFROMMP(mpl) ; 


if  (WinlnSendMsg(hab)) 

{ 

/*  parse  and  display  error  message  */ 
sprintf(szMsg,  "Error  code  %d  occurred",  errorcode); 
Wi nMessageBox ( HWND_DESKTOP , 
hwnd, 
szMsg, 

"Error  notification", 

0, 

MB_N0IC0N  | MB_0K) ; 

} 


/* 

/* 

/* 

/* 

/* 


client-window  handle 
body  of  the  message 
title  of  the  message 
message  box  id 
icon  and  button  flags 


*/ 

*/ 

*/ 

*/ 

*/ 
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WinlnsertLboxItem  - 
Insert  Listbox  Item 


#define  INCL_WINWINDOWMGR  /*  Or  use  INCL_WIN  or  INCL_PM  7 


SHORT  WinlnsertLboxItem  (HWND  hwndLbox,  SHORT  slndex,  PSZ  pszText) 


This  macro  inserts  text  into  a list  box  at  index,  index  may  be  a LIT_  constant.  This  macro  returns  the 
actual  index  where  it  was  inserted. 

Parameters 

hwndLbox  (HWND)  - input 
List  box  handle. 

slndex  (SHORT)  - input 

Index  of  the  list  box  item. 

pszText  (PSZ)  - input 
Text  to  be  inserted. 


Returns 

Actual  index  where  it  was  inserted. 


Remarks 

This  macro  expands  to: 

Idefine  WinInsertLboxItem(hwndLbox,  slndex,  pszText) 

( ( SHORT )Wi nSendMsg (hwndLbox , 

LMJNSERTITEM, 
MPFROMSHORT(sIndex) , 
MPFROMP(pszText))) 

This  function  requires  the  existence  of  a message  queue. 


Related  Functions 

• WinSendMsg 


Related  Messages 

• LMJNSERTITEM 
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WinlnsertLboxItem 
Insert  Listbox  Item 


Example  Code 

This  example  calls  WinlnsertLboxItem  to  Insert  items  In  a list  box  as  part  of  initializing  a dialog 
(WMJNITDLG  message). 


Idefine  INCL_WINWINDOWMGR  /*  Window  Manager  Functions  */ 
fdefine  INCL_WINLISTBOXES  /*  Window  List  Box  definitions  */ 
linclude  <os2.h> 

SHORT  slndex;  /*  inserted  item  index  */ 
HWND  hwndLbox;  /*  list  box  window  handle  */ 
MPARAM  mpl;  /*  Parameter  1 (window  handle)  */ 
/*  Array  of  list  box  item  names  */ 

PSZ  pszltems [3]  = {"Iteml",  "Item2",  "Item3"}; 


case  WMJNITDLG: 


y*******************************  j 

/*  Initialize  List  Box  Control  */ 

j ******************************* j 

/*  get  handle  of  list  box  */ 
hwndLbox  = HWNDFROMMP(mpl) ; 

/*  insert  3 items  into  list  box  */ 

slndex  = WinInsertLboxItem(hwndLbox,  LIT_END,  pszltems[0]) ; 
slndex  = WinInsertLboxItem(hwndLbox,  LIT_END,  pszltems[l] ) ; 
slndex  = WinInsertLboxItem(hwndLbox,  LIT_END,  pszltems[2]); 
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WinlntersectRect  - 
Intersect  Rectangle 


#define  INCL_WINRECTANGLES  /*  Or  use  INCL_WIN  or  INCL_PM  */ 


BOOL  WinlntersectRect  (HAB  hab,  PRECTL  prciDest,  PRECTL  prcIRectl,  PRECTL  prclRect2) 


This  function  calculates  the  intersection  of  the  two  source  rectangles  and  returns  the  result  in  the 
destination  rectangle. 


Parameters 

hab  (HAB)  - input 

Anchor-block  handle. 

prciDest  (PRECTL)  - output 
Intersection  rectangle. 

Is  the  intersection  of  prcIRectl  and  prclRect2. 

Note:  The  value  of  each  field  in  this  structure  must  be  in  the  range  —32  768  through  32  767.  The 
data  type  WRECT  can  also  be  used,  if  supported  by  the  language. 

prcIRectl  (PRECTL)  - input 
First  rectangle. 

Note:  The  value  of  each  field  in  this  structure  must  be  in  the  range  —32  768  through  32  767.  The 
data  type  WRECT  can  also  be  used,  if  supported  by  the  language. 

prclRect2  (PRECTL)  - input 
Second  rectangle. 

Note:  The  value  of  each  field  in  this  structure  must  be  in  the  range  —32  768  through  32  767.  The 
data  type  WRECT  can  also  be  used,  if  supported  by  the  language. 


Returns 

Success  indicator: 

TRUE  Source  rectangles  intersect 

FALSE  Source  rectangles  do  not  intersect,  or  an  error  occurred. 

Remarks 

If  there  is  no  intersection,  an  empty  rectangle  is  returned  in  prciDest. 

Related  Functions 

• WinCopyRect 

• WinEqualRect 

• WinFillRect 

• WinlnflateRect 

• WinlsRectEmpty 

• WinOffsetRect 

• WinPtlnRect 

• WinSetRect 

• WinSetRectEmpty 

• WinSubtractRect 

• WinUnionRect 
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WinlntersectRect  - 
Intersect  Rectangle 

Example  Code 

This  example  determines  the  intersection  of  two  rectangles  and  places  the  result  in  a third  rectangle 
structure. 

fdefine  INCL_WINRECT ANGLES  /*  Window  Rectangle  Functions  */ 
finclude  <os2.h> 


BOOL  f Success;  /*  success  indicator  */ 
HAB  hab;  /*  anchor-block  handle  */ 
RECTL  prcl Recti  = {0,0,100,100};  /*  rectangle  1 */ 
RECTL  prclRect2  = {0,0,200,200};  /*  rectangle  2 */ 
RECTL  prclDest;  /*  destination  rectangle  */ 


f Success  = WinlntersectRect (hab,  &prclDest,  &prcl Recti, 

&prclRect2) ; 
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WinlnvalidateRect  - 
Invalidate  Rectangle 


#define  INCL_WINWINDOWMGR  /*  Or  use  INCL_WIN  or  INCL_PM  */ 


BOOL  WinlnvalidateRect  (HWNO  hwnd,  PRECTL  prcIPrc,  BOOL  flncludeCUppedChildren) 


This  function  adds  a rectangle  to  a window’s  update  region. 

Parameters 

hwnd  (HWND)  - input 

Handle  of  window  whose  update  region  is  to  be  changed: 

HWND_DESKTOP  This  function  applies  to  the  whole  screen  (or  desktop) 

Other  Handle  of  window  whose  update  region  is  to  be  changed. 

prcIPrc  (PRECTL)  - input 
Update  rectangle. 

Note:  The  value  of  each  field  in  this  structure  must  be  in  the  range  —32  768  through  32  767.  The 
data  type  WRECT  can  also  be  used,  if  supported  by  the  language. 

NULL  The  whole  window  is  to  be  added  into  the  window’s  update  region. 

Other  Rectangle  to  be  added  to  the  window’s  update  region. 

flncludeCUppedChildren  (BOOL)  - input 
Invalidation-scope  indicator: 

TRUE  Include  the  descendants  of  hwnd  in  the  invalid  rectangle. 

FALSE  Include  the  descendants  of  hwnd  in  the  invalid  rectangle,  but  only  if  the  parent  does  not 
have  a WS_CLIPCHILDREN  style. 

Returns 

Success  indicator: 

TRUE  Successful  completion 
FALSE  Error  occurred. 

Possible  returns  from  WinGetLastError 

PMERR  INVALID  HWND  An  invalid  window  handle  was  specified. 

PMERR_INVALID_FLAG  An  invalid  bit  was  set  for  a parameter.  Use  constants 

defined  by  PM  for  options,  and  do  not  set  any  reserved 
bits. 


Remarks 

The  update  region  is  a subregion  of  a window  that  is  deemed  “invalid”  or  incorrect  in  visual  terms 
and  in  need  of  redrawing. 

If  the  window  has  a CS_SYNCPAINT  style,  it  is  redrawn  during  the  processing  of  this  function  and  the 
update  region  should  be  NULL  on  return  from  this  function. 

If  the  window  has  a WS_CLIPCHILDREN  style  with  part  of  its  update  region  overlapping  child 
windows  with  a CS_SYNCPAINT  style,  those  children  are  updated  before  this  function  returns. 

This  function  should  not  be  called  in  response  to  a WM_PAINT  request  for  windows  of  style 
CS_SYNCPAINT.  CS_SYNCPAINT  means  that  windows  are  updated  synchronously  when  invalidated, 
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WinlnvalidateRect  - 
Invalidate  Rectangle 


which  generates  a WMPAINT  message.  Thus,  invalidating  the  window  in  response  to  a WMPAINT 
message  would  cause  another  invalidate,  and  another  WM  PAINT,  and  so  on. 


Related  Functions 

• WinBeginPaint 

• WinEnableWindowllpdate 

• WinEndPaint 

• WinExcludeUpdateRegion 

• WinGetClipPS 

• WinGetPS 

• WinGetScreenPS 

• WinlnvalidateRegion 

• WinlsWindowShowing 

• WinlsWindowVisible 

• WinLockVisRegions 

• WinOpenWindowDC 

• WinQueryUpdateRect 

• WinQueryUpdateRegion 

• WinRealizePalette 

• WinReleasePS 

• WinShowWindow 

• WinllpdateWindow 

• WinValidateRect 

• WinValidateRegion 

Related  Messages 

• WM_ERASEWINDOW 

• WM_PAINT 

Example  Code 

This  example  gets  the  dimensions  of  the  window  and  calls  WinlnvalidateRect  to  invalidate  the 
window.  The  application  will  be  sent  a WM  PAINT  message  with  the  entire  window  as  the  update 
rectangle. 

fdefine  INCL_WINWINDOWMGR  /*  Window  Manager  Functions  */ 

linclude  <os2.h> 

HWND  hwnd;  /*  parent  window  */ 

RECTL  rcl;  /*  update  region  */ 

WinQueryWindowRect(hwnd,  &rcl); 

Winlnval idateRect(hwnd,  /*  window  to  invalidate  */ 

&rcl,  /*  invalid  rectangle  */ 

FALSE);  /*  do  not  include  children  */ 
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WinlnvalidateRegion  - 
Invalidate  Region 


#define  INCL_WINWINDOWMGR  /*  Or  use  INCL_WIN  or  INCL_PM  */ 


BOOL  WlnlnvalldateRegion  (HWNO  hwnd,  HRGN  hrgn,  BOOL  flnciudeCUppedChlldren) 


This  function  adds  a region  to  a window’s  update  region. 

Parameters 

hwnd  (HWND)  - input 

Handle  of  window  whose  update  region  is  to  be  changed. 

HWND_DESKTOP  This  function  applies  to  the  whole  screen  (or  desktop). 

Other  Handle  of  window  whose  update  region  is  to  be  changed, 

hrgn  (HRGN)  - input 

Handle  of  the  region  to  be  added  to  the  update  region  of  the  window. 

NULLHANDLE  The  whole  window  is  to  be  added  into  the  window’s  update  region. 

Other  Handle  of  the  region  to  be  added  to  the  window’s  update  region. 

flncludeClIppedChildren  (BOOL)  - input 
Invalidation-scope  indicator: 

TRUE  Include  the  descendants  of  hwnd  in  the  invalid  rectangle. 

FALSE  Include  the  descendants  of  hwnd  in  the  invalid  rectangle,  but  only  if  the  parent  does  not 
have  a WS_CLIPCHILDREN  style. 

Returns 

Success  indicator: 

TRUE  Successful  completion 
FALSE  Error  occurred. 

Possible  returns  from  WinGetLastError 

PMERRJNVALIDHWND 
PMERRHRGNBUSY 

PMERRINVALIDFLAG 


An  invalid  window  handle  was  specified. 

An  internal  region  busy  error  was  detected.  The  region 
was  locked  by  one  thread  during  an  attempt  to  access  it 
from  another  thread. 

An  invalid  bit  was  set  for  a parameter.  Use  constants 
defined  by  PM  for  options,  and  do  not  set  any  reserved 
bits. 


Remarks 

The  update  region  is  a subregion  of  a window  that  is  deemed  “invalid”  or  incorrect  in  visual  terms 
and  is  in  need  of  redrawing. 

If  the  window  has  a CS_SYNCPAINT  style,  it  is  redrawn  during  the  processing  of  this  function  and  the 
update  region  should  be  NULL  on  return  from  this  function. 

If  the  window  has  a WS_CLIPCHILDREN  style  with  part  of  its  update  region  overlapping  child 
windows  with  a CS_SYNCPAINT  style,  those  children  are  updated  before  this  function  returns. 

This  function  should  not  be  called  in  response  to  a WM_PAINT  request  for  windows  of  style 
CS_SYNCPAINT.  CS_SYNCPAINT  means  that  windows  are  updated  synchronously  when  invalidated, 
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WinlnvalidateRegion 
Invalidate  Region 


which  generates  a WMPAINT  message.  Thus,  invalidating  the  window  in  response  to  a WMPAINT 
message  would  cause  another  invalidate,  another  WM  PAINT,  and  so  on. 


Related  Functions 

• WinBeginPaint 

• WinEnableWindowllpdate 

• WinEndPaint 

• WinExcludellpdateRegion 

• WinGetClipPS 

• WinGetPS 

• WinGetScreenPS 

• WinlnvalidateRect 

• WinlsWindowShowing 

• WinlsWindowVisible 

• WinLockVisRegions 

• WinOpenWindowDC 

• WinQueryllpdateRect 

• WinQueryllpdateRegion 

• WinRealizePalette 

• WinReleasePS 

• WinShowWindow 

• WinUpdateWindow 

• WinValidateRect 

• WinValidateRegion 

Related  Messages 

• WM_ERASEWINDOW 

• WM_PAINT 

Example  Code 

This  example  invalidates  the  entire  window  by  adding  the  whole  window  to  the  window's  update 
region  using  WinlnvalidateRegion.  This  single  call  accomplishes  the  same  as  paired  calls  to 
WinQueryWindowRect  and  WinlnvalidateRect.  If  less  than  the  entire  window  is  desired,  the  NULL 
value  in  the  second  parameter  can  be  replaced  with  a region  handle  that  corresponds  to  a subregion 
of  the  window. 

fdefine  INCL_WINWINDOWMGR  /*  Window  Manager  Functions  */ 

finclude  <os2.h> 

HWND  hwnd;  /*  window  handle  */ 

WinInvalidateRegion(hwnd,  NULLHANDLE,  0); 
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WinlnvertRect  - 
Invert  Rectangle 


#define  INCLJVINWINDOWMGR  /*  Or  use  INCL_WIN  or  INCL_Pfd  7 


BOOL  WinlnvertRect  (HPS  hps,  PRECTL  prcIRect) 


This  function  inverts  a rectangular  area. 


Parameters 

hps  (HPS)  - input 

Presentation-space  handle. 

The  presentation  space  contains  the  rectangle  to  be  inverted. 

prcIRect  (PRECTL)  - input 
Rectangle  to  be  inverted. 

Note:  The  value  of  each  field  in  this  structure  must  be  in  the  range  —32  768  through  32  767.  The 
data  type  WRECT  can  also  be  used,  if  supported  by  the  language. 


Returns 

Success  indicator: 

TRUE  Successful  completion 
FALSE  Error  occurred. 

Remarks 

Inversion  is  a logical-NOT  operation  and  has  the  effect  of  flipping  the  bits  of  each  pel. 

Related  Functions 

• WinDrawBitmap 

• WinDrawBorder 

• WinDrawPointer 

• WinDrawText 

• WinFillRect 

• WinGetSysBitmap 

• WinQueryPresParam 

• WinRemovePresParam 

• WinScrollWindow 

• WinSetPresParam 
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WinlnvertRect  - 
Invert  Rectangle 

Example  Code 

This  example  inverts  a rectangle  if  the  mouse  button  is  released  (WM_BUTTON1UP)  within  the 
rectangle  (WinPtlnRect);  the  presentation  space  handle  is  obtained  via  WinBeginPaint. 


Idefine  INCL_WINWINDOWMGR  /*  Window  Manager  Functions  */ 
linclude  <os2.h> 

BOOL  f Success;  /*  success  indicator  */ 
HAB  hab;  /*  anchor-block  handle  */ 
RECTL  prcl Recti  = {0,0,100,100};  /*  rectangle  */ 
HWND  hwnd;  /*  client  window  handle  */ 
HPS  hps;  /*  presentation-space  handle  */ 
P0INTL  ptl;  /*  current  mouse  position  */ 
MPARAM  mpl;  /*  Parameter  1 (x,y)  point  value  */ 


case  WM_BUTT0N1UP: 

ptl  .x  = (LONG)  SHORTlFROMMP(mpl); 
ptl .y  = (LONG)  SH0RT2FR0MMP(mpl); 

if  (WinPtInRect(hab,  &prclRectl,  &ptl ) ) 

{ 

hps  = WinBeginPaint(hwnd,  NULLHANDLE,  SprclRectl); 
fSuccess  = WinInvertRect(hps,  &prclRectl); 
WinEndPaint(hps) ; 

} 
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WinlsChild  - 
Is  Child 


#define  INCL_WINWINDOWMGR  /*  Or  use  INCL_WIN  or  INCL_PM  */ 


BOOL  WinlsChild  (HWND  hwndChlld,  HWND  hwndParent) 


This  function  tests  if  one  window  is  a descendant  of  another  window. 


Parameters 

hwndChlld  (HWND)  - input 
Child-window  handle. 

hwndParent  (HWND)  - input 
Parent-window  handle. 


Returns 

Related  indicator: 

TRUE  Child  window  is  a descendant  of  the  parent  window,  or  is  equal  to  it 

FALSE  Child  window  is  not  a descendant  of  the  parent,  or  is  an  Object  Window  (even  if 

hwndParent  is  specified  as  the  desktop  or  HWND_DESKTOP),  or  an  error  occurred. 

Possible  returns  from  WinGetLastError 

PMERR  INVALID  HWND  An  invalid  window  handle  was  specified. 

Related  Functions 

• WinBeginEnumWindows 

• WinEndEnumWindows 

• WinEnumDIgltem 

• WinGetNextWindow 

• WinMultWindowFromIDs 

• WinQueryWindow 

• WinSetOwner 

• WinSetParent 

Example  Code 

This  example  uses  WinlsChild  to  determine  if  one  window  is  a descendant  of  another  window. 

fdefine  INCL_WINWINDOWMGR  /*  Window  Manager  Functions  */ 

finclude  <os2.h> 

HWND  hwndChild;  /*  child  window  to  check  */ 

HWND  hwndParent;  /*  parent  window  to  check  */ 

if  (WinlsChil d (hwndChi Id,  hwndParent)) 

{ 

/*  hwndChild  is  a descendant  of  hwndParent  */ 

} 

else 

{ 

/*  hwndChild  is  not  a descendant  of  hwndParent  */ 

} 
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WinlsControlEnabled 
Is  Control  Enabled 


#define  INCL_WINWINDOWMGR  /*  Or  use  INCL_WIN  or  INCL_PM  7 


BOOL  WinlsControlEnabled  (HWND  hwndDIg,  USHORT  usld) 


This  macro  returns  the  state  (enable/disable)  of  the  specified  item  in  the  dialog  template  within  a 
dialog  box. 


Parameters 

hwndDIg  (HWND)  - input 
Dialog  window  handle. 

usld  (USHORT)  - input 

Identity  of  the  specified  item. 


Returns 

Success  indicator: 

TRUE  Successful  completion 
FALSE  Error  occurred. 

Remarks 

This  macro  expands  to: 

fdefine  WinIsControlEnabled(hwndDlg,  usld) 

((BOOL)WinlsWindowEnabled(WinWindowFromlD(hwndDlg,  usld))) 

This  function  requires  the  existence  of  a message  queue. 

Related  Functions 

• WinlsWindowEnabled 

• WinWindowFromID 
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WinlsControlEnabled  - 
Is  Control  Enabled 


Example  Code 

This  example  uses  WinlsControlEnabled  to  determine  if  a selected  control  is  valid;  if  it  is  not,  an 
error  message  box  is  displayed. 


fdefine  INCL_WINWINDOWMGR  /*  Window  Manager  Functions  */ 
fdefine  INCL_WINDIALOGS  /*  Window  Dialog  Mgr  Functions  */ 
finclude  <os2.h> 


HWND  hwndDlg;  /*  dialog  window 

MPARAM  mpl;  /*  Parameter  1 

USHORT  usld;  /*  dialog  control  id 

case  WM_C0NTR0L: 

usld  = SHORTlFROMMP(mpl); 


*/ 

*/ 

*/ 


if  (!WinIsControlEnabled(hwndDlg,  usld)) 


{ 

WinMessageBox(HWND_DESKTOP, 

hwndDlg, 

"Control  is  not  valid", 
"Error  notification", 

0, 

MB_N0IC0N  | MB_0K) ; 


/*  client-window  handle 
/*  body  of  the  message 
/*  title  of  the  message 
/*  message  box  id 
/*  icon  and  button  flags 


} 


*/ 

*/ 

*/ 

*/ 

*/ 
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WinlsMenultemChecked 
Is  Menu  Item  Checked 


#define  INCL_WINWINDOWMGR  /*  Or  use  INCL_WIN  or  INCL_PM  */ 


BOOL  WinlsMenultemChecked  (HWND  hwndMenu,  USHORT  usld) 


This  macro  returns  the  state  (checked/not  checked)  of  the  identified  menu  item. 

Parameters 

hwndMenu  (HWND)  - input 
Menu  window  handle. 

usld  (USHORT)  - input 

Identity  of  the  menu  item. 


Returns 

Success  indicator: 

TRUE  Successful  completion 
FALSE  Error  occurred. 

Remarks 

This  macro  expands  to: 

fdefine  WinIsMenuItemChecked(hwndMenu,  usld) 

( (BOOL)Wi nSendMsg (hwndMenu , 

MMQUERYITEMATTR, 
MPFR0M2SH0RT(usId,  TRUE), 
MPFR0M2SH0RT (MIA_CHECKED) ) ) 

This  function  requires  the  existence  of  a message  queue. 

Related  Functions 

• WinSendMsg 

Related  Messages 

• MM_QUERYITEMATTR 
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WinlsMenultemChecked  - 
Is  Menu  Item  Checked 


Example  Code 

This  example  uses  WinlsMenultemChecked  to  query  the  check  attribute  of  a selected  menu  item 
before  setting  the  check  state  of  that  menu  item. 

fdefine  INCLJIINWINDOWMGR  /*  Window  Manager  Functions  */ 


linclude  <os2.h> 
USHORT  usltemld; 

/*  menu  item  id 

*/ 

HWND 

hwndMenu; 

/*  menu  handle 

*/ 

BOOL 

usChkstate; 

/*  new  checked  state 

*/ 

BOOL 

fSuccess; 

/*  success  indicator 

*/ 

MPARAM 

mpl; 

/*  Parameter  1 (menu  item  id) 

*/ 

MPARAM 

mp2; 

/*  Parameter  2 (menu  handle) 

*/ 

case  WM 

MENUSELECT: 

usltemld  = SHORTlFROMMP(mpl) ; 
hwndMenu  = HWNDFR0MMP(mp2) ; 

/*  query  current  check  state  */ 

usChkstate  = WinIsMenuItemChecked(hwndMenu,  usltemld); 

/*  set  menu  item  check  state  */ 

fSuccess  = WinCheckMenuItem(hwndMenu,  usltemld,  usChkstate); 
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Win  IsMenultemEnabled 
Is  Menu  Item  Enabled 


#define  INCL_WINWINDOWMGR  /*  Or  use  INCL_WIN  or  INCL_PM  */ 


BOOL  WinlsMenultem Enabled  (HWND  hwndMenu,  USHORT  usld) 


This  macro  returns  the  state  (enable/disable)  of  the  menu  item  specified. 

Parameters 

hwndMenu  (HWND)  - input 
Menu  window  handle. 

usld  (USHORT)  - input 

Identity  of  the  menu  item. 


Returns 

Success  indicator: 

TRUE  Successful  completion 
FALSE  Error  occurred. 

Remarks 

This  macro  expands  to: 

Idefine  WinIsMenuItemEnabled(hwndMenu,  usld) 

(! (BOOL)WinSendMsg(hwndMenu, 

MM_QUER YITEMATTR , 

MPFR0M2SH0RT (usld,  TRUE), 
MPFROMSHORT(MIA_DISABLED) ) ) 

This  function  requires  the  existence  of  a message  queue. 


Related  Functions 

• WinSendMsg 

Related  Messages 

• MM_QUERYITEMATTR 
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WinlsMenultemEnabled  - 
Is  Menu  Item  Enabled 


Example  Code 

This  example  uses  WinlsMenultemEnabled  to  determine  if  a selected  menu  item  is  available  for  use. 
If  the  item  is  not  valid  (WinlsMenultemValid)  or  not  enabled,  a beep  is  emitted. 


fdefine  I NC L_WI NMESSAGEMGR  /*  Window  Message  Functions  */ 
fdefine  INCL_WINMENUS  /*  Window  Menu  Functions  */ 
fdefine  INCL_DOSPROCESS  /*  OS/2  Process  Functions  */ 
finclude  <os2.h> 

MPARAM  mpl;  /*  Parameter  1 (recti  structure)  */ 
MPARAM  mp2;  /*  Parameter  2 (frame  boolean)  */ 
USHORT  usltemld;  /*  menu  item  id  */ 
HWND  hwndMenu;  /*  menu  handle  */ 


case  WM_MENUSELECT : 

usltemld  = SHORTlFROMMP(mpl) ; 
hwndMenu  = HWNDFR0MMP(mp2) ; 

/*  if  menu  item  is  not  valid  or  enabled,  emit  beep  */ 
if  (!WinIsMenuItemValid(hwndMenu,  usltemld)  || 
!WinIsMenuItemEnabled(hwndMenu,  usltemld)) 
DosBeep(80O,100L); 
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WinlsMenultemValid 
Is  Menu  Item  Valid 


#define  INCL_WINWINDOWMGR  /*  Or  use  INCL_WIN  or  INCL_PM  7 


BOOL  WinlsMenultemValid  (HWND  hwndMenu,  USHORT  usld) 


This  macro  returns  TRUE  if  the  specified  item  is  a valid  choice. 


Parameters 

hwndMenu  (HWND)  - input 
Menu  window  handle. 

usld  (USHORT)  - input 

Identity  of  the  menu  item. 


Returns 

Success  indicator: 

TRUE  Successful  completion 
FALSE  Error  occurred. 

Remarks 

This  macro  expands  to: 

fdefine  WinIsMenuItemValid(hwndMenu,  usld) 

( (BOOL) Wi nSendMsg (hwndMenu , 

MMISITEMVALID, 

MPFR0M2SH0RT (usld,  TRUE), 
MPFR0MSH0RT( FALSE))) 

This  function  requires  the  existence  of  a message  queue. 


Related  Functions 

• WinSendMsg 

Related  Messages 

• MMJSITEMVALID 
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WinlsMenultemValid  - 
Is  Menu  Item  Valid 


Example  Code 

This  example  uses  WinlsMenultemValid  to  determine  if  a selected  menu  item  is  available  for  use.  If 
the  item  is  not  enabled  (WinlsMenultemEnabled)  or  not  valid,  a beep  is  emitted. 


Idefine  INCL_WINMESSAGEMGR  /*  Window  Message  Functions  */ 
Idefine  INCL_WINMENUS  /*  Window  Menu  Functions  */ 
Idefine  INCL_DOSPROCESS  /*  OS/2  Process  Functions  */ 
linclude  <os2.h> 

MPARAM  mpl;  /*  Parameter  1 (recti  structure)  */ 
MPARAM  mp2;  /*  Parameter  2 (frame  boolean)  */ 
USHORT  usltemld;  /*  menu  item  id  */ 
HWNO  hwndMenu;  /*  menu  handle  */ 


case  WM_MENUSELECT : 

usltemld  = SHORTlFROMMP(mpl) ; 
hwndMenu  = HWNDFR0MMP(mp2) ; 

/*  if  menu  item  is  not  valid  or  enabled,  emit  beep  */ 
if  (!WinIsMenuItemValid(hwndMenu,  usltemld)  || 

! WinlsMenultemEnabled (hwndMenu,  usltemld)) 
DosBeep(800,100L) ; 
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WinlsPhysInputEnabled  - 
Is  Physical  Input  Enabled 


#define  INCL_WININPUT  /*  Or  use  INCL_WIN  or  INCL_PM  7 


BOOL  WinlsPhysInputEnabled  (HWND  hwndDeskTop) 


This  function  returns  the  status  of  hardware  input  (on/off). 

Parameters 

hwndDeskTop  (HWND)  - input 
Desktop-window  handle: 

HWND  DESKTOP  The  desktop-window  handle 

Returns 

Return  value. 

TRUE  If  input  is  enabled. 

FALSE  If  input  is  disabled. 

Related  Functions 

• WinEnablePhysinput 

Example  Code 

This  example  uses  WinlsPhysInputEnabled  to  determine  if  physical  input  is  enabled;  if  it  is  not,  then 
WinEnablePhysinput  is  called  to  enable  it. 

fdefine  INCL_WININPUT  /*  Window  Input  Functions  */ 

finclude  <os2.h> 


i f ( ! WinlsPhysInputEnabl ed(HWND_DESKTOP) ) 
/*  enable  queuing  of  physical  input  */ 
WinEnablePhysInput(HWND_DESKTOP,  TRUE) ; 


8-222  PM  Programming  Reference 


WinlsRectEmpty  - 
Is  Rectangle  Empty 


#define  INCL_WINRECTANGLES  /*  Or  use  INCL_WIN  or  INCL_PM  7 


BOOL  WinlsRectEmpty  (HAB  hab,  PRECTL  prclprc) 


This  function  checks  whether  a rectangle  is  empty. 


Parameters 

hab  (HAB)  - input 

Anchor-block  handle. 

prclprc  (PRECTL)  - input 
Rectangle  to  be  checked. 

Note:  The  value  of  each  field  in  this  structure  must  be  in  the  range  —32  768  through  32  767.  The 
data  type  WRECT  can  also  be  used,  if  supported  by  the  language. 


Returns 

Empty  indicator: 

TRUE  Rectangle  is  empty 
FALSE  Rectangle  is  not  empty. 

Remarks 

A rectangle  has  area  if  its  left  edge  coordinate  is  less  than  its  right  edge  coordinate,  and  its  bottom 
edge  coordinate  is  less  than  its  top  edge  coordinate.  An  empty  rectangle  is  one  with  no  area. 


Related  Functions 

• WinCopyRect 

• WinEqualRect 

• WinFillRect 

• WinlnflateRect 

• WinlntersectRect 

• WinOffsetRect 

• WinPtlnRect 

• WinSetRect 

• WinSetRectEmpty 

• WinSubtractRect 

• WinUnionRect 

Example  Code 

This  example  checks  if  a rectangle  is  empty  (i.e.  it  has  no  area). 

fdefine  INCL_WINRECT ANGLES  /*  Window  Rectangle  Functions  */ 

linclude  <os2.h> 

BOOL  f Empty;  /*  empty  indicator  */ 

HAB  hab;  /*  anchor-block  handle  */ 

RECTL  prcl Recti  = {0,0,100,100};  /*  rectangle  */ 

fEmpty  = WinIsRectEmpty(hab,  SprclRectl); 
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WinlsThreadActive 
Is  Thread  Active 


#define  INCL_WINWINDOWMGR  /*  Or  use  INCL_WIN  or  INCL_PM  */ 


BOOL  WinlsThreadActive  (HAB  hab) 


This  function  determines  whether  the  active  window  belongs  to  the  calling  execution  thread. 

Parameters 

hab  (HAB)  - input 

Anchor-block  handle  of  calling  thread. 


Returns 

Active-window  indicator: 

TRUE  Active  window  belongs  to  calling  thread 
FALSE  Active  window  does  not  belong  to  calling  thread. 

Related  Functions 

• WinEnableWindow 

• WinlsWindow 

• WinlsWindowEnabled 

• WinQueryDesktopWindow 

• WinQueryObjectWindow 

• WinQueryWindowDC 

• WinQueryWindowProcess 

• WinQueryWindowRect 

• WinWindowFromDC 

• WinWindowFromID 

• WinWindowFromPoint 
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WinlsThreadActive  - 
Is  Thread  Active 


Example  Code 

This  example  uses  WinlsThreadActive  to  verify  that  the  active  window  belongs  to  the  current  thread 
before  querying  and  enabling  the  system  menu  window  via  WinlsWindowEnabled  and 
WinEnableWindow. 


Idefine  INCL_WINWINDOWMGR  /*  Window  Manager  Functions  */ 
Idefine  INCL_WINFRAMEMGR  /*  Window  Frame  Functions  */ 
#include  <os2.h> 

HAB  hab;  /*  anchor-block  handle  */ 
HWND  hwndSysmenu;  /*  system  menu  window  */ 
HWND  hwnd;  /*  parent  window  */ 
BOOL  fSuccess;  /*  success  indicator  */ 


/*  if  the  active  window  belongs  to  the  current  thread,  query  the 
enabled  status  of  the  system  menu  */ 
if  (WinlsThreadActive (hab)) 

{ 

/*  obtain  handle  for  system  menu  */ 
hwndSysmenu  = WinWindowFromID(hwnd,FID_SYSMENU) ; 

/*  if  system  menu  is  not  enabled,  enable  it  */ 
if  ( ! WinlsWi ndowEnabl ed (hwndSysmenu) ) 

fSuccess  = WinEnableWindow(hwndSysmenu,  TRUE); 

} 
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WinlsWindow 
Is  Window 


#define  INCL_WINWINDOWMGR  /*  Or  use  INCL_WIN  or  INCL_PM  7 


BOOL  WinlsWindow  (HAB  hab,  HWND  hwnd) 


This  function  determines  if  a window  handle  is  valid. 


Parameters 

hab  (HAB)  - input 

Anchor-block  handle. 

hwnd  (HWND)  - input 
Window  handle. 


Returns 

Validity  indicator: 

TRUE  Window  handle  is  valid 
FALSE  Window  handle  is  not  valid. 

Possible  returns  from  WinGetLastError 

PMERRJNVALID  HWND  An  invalid  window  handle  was  specified. 

Related  Functions 

• WinEnableWindow 

• WinlsThreadActive 

• WinlsWindowEnabled 

• WinQueryDesktopWindow 

• WinQueryObjectWindow 

• WinQueryWindowDC 

• WinQueryWindowProcess 

• WinQueryWindowRect 

• WinWindowFromDC 

• WinWindowFromID 

• WinWindowFromPoint 
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WinlsWindow  - 
Is  Window 


Example  Code 

This  example  uses  WinlsWindow  to  verify  that  the  parent  window  is  valid  before  querying  and 
enabling  the  system  menu  window  via  WinlsWindowEnabled  and  WinEnableWindow. 


fdefine  INCL_WINWINDOWMGR  /*  Window  Manager  Functions  */ 
fdefine  INCL_WINFRAMEMGR  /*  Window  Frame  Functions  */ 
finclude  <os2.h> 

HAB  hab;  /*  anchor-block  handle  */ 
HWND  hwndSysmenu;  /*  system  menu  window  */ 
HWND  hwnd;  /*  parent  window  */ 
BOOL  f Success;  /*  success  indicator  */ 


/*  if  handle  specifies  a valid  window,  query  the  enabled  status  of 
the  system  menu  */ 
if  (WinIsWindow(hab,  hwnd)) 

{ 

/*  obtain  handle  for  system  menu  */ 
hwndSysmenu  = WinWindowFromID(hwnd,FID_SYSMENU) ; 

/*  if  system  menu  is  not  enabled,  enable  it  */ 
if  ( !WinIsWindowEnabled(hwndSysmenu)) 

fSuccess  = WinEnableWindow(hwndSysmenu,  TRUE); 

} 
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WinlsWindowEnabled  - 
Query  Window  Enabled  State 


#define  INCL_WINWINDOWMGR  /*  Or  use  INCL_WIN  or  INCL_PM  7 


BOOL  WinlsWindowEnabled  (HWND  hwnd) 


This  function  returns  the  enabled/disabled  state  of  a window. 

Parameters 

hwnd  (HWND)  - input 
Window  handle. 


Returns 

Enabled-state  indicator: 

TRUE  Window  is  enabled 
FALSE  Window  is  not  enabled. 

Possible  returns  from  WinGetLastError 

PMERR  INVALID  HWND  An  invalid  window  handle  was  specified. 

Related  Functions 

• WinEnableWindow 

• WinlsThreadActive 

• WinlsWindow 

• WinQueryDesktopWindow 

• WinQueryObjectWindow 

• WinQueryWindowDC 

• WinQueryWindowProcess 

• WinQueryWindowRect 

• WinWindowFromDC 

• WinWindowFromID 

• WinWindowFromPoint 
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WinlsWindowEnabled  - 
Query  Window  Enabled  State 


Example  Code 

This  example  uses  WinlsWindowEnabled  to  check  that  the  parent  window  is  currently  disabled 
before  calling  WinEnableWindow  to  enable  the  system  menu  window. 


fdefine  INCL_WINWINDOWMGR  /*  Window  Manager  Functions  */ 
fdefine  INCL_WINFRAMEMGR  /*  Window  Frame  Functions  */ 
finclude  <os2.h> 


HAB  hab; 

HWND  hwndSysmenu; 

HWND  hwnd; 

BOOL  f Success; 


/*  anchor-block  handle 
/*  system  menu  window 
/*  parent  window 
/*  success  indicator 


*/ 

*/ 

*/ 

*/ 


/*  obtain  handle  for  system  menu  */ 
hwndSysmenu  = WinWindowFromIO(hwnd,FID_SYSMENU) ; 

/*  if  system  menu  is  not  enabled,  enable  it  */ 
if  ( ! Wi n I sWi ndowEnabl ed ( hwndSysmenu) ) 

fSuccess  = WinEnableWindow(hwndSysmenu,  TRUE); 
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WinlsWindowShowing  - 
Query  Window  Showing 


#define  INCL_WINWINDOWMGR  /*  Or  use  INCL_WIN  or  INCL_PM.  Also  in  COMMON  section  */ 


BOOL  WinlsWindowShowing  (HWND  hwnd) 


This  function  determines  whether  any  part  of  the  window  hwnd  is  physically  visible. 

Parameters 

hwnd  (HWND)  - input 
Window  handle. 


Returns 

Showing  state  indicator: 

TRUE  Some  part  of  the  window  is  displayed  on  the  screen 
FALSE  No  part  of  the  window  is  displayed  on  the  screen. 

Possible  returns  from  WinGetLastError 

PMERRJNVALID  HWND  An  invalid  window  handle  was  specified. 

Remarks 

This  function  is  useful  for  applications  that  constantly  output  new  information.  If  value  FALSE  is 
returned  (that  is,  no  part  of  the  window  is  physically  visible),  the  application  can  choose  not  to 
redraw,  since  redrawing  is  not  necessary. 

If  an  application  is  using  WinlsWindowShowing,  it  must  issue  the  call  every  time  it  has  new 
information  that  needs  to  be  updated.  If  this  is  not  done,  invalid  screen  content  could  result.  The 
alternative  to  this  approach  for  a constantly-updating  application  that  has  new  information  is  for  it  to 
invalidate  its  window  and  redraw  within  a WinBeginPaint  - WinEndPaint  sequence. 

FALSE  is  returned  if  the  PM  session  is  not  currently  visible. 


Related  Functions 

• WinBeginPaint 

• WinEnableWindowUpdate 

• WinEndPaint 

• WinExcludeUpdateRegion 

• WinGetClipPS 

• WinGetPS 

• WinGetScreenPS 

• WinlnvalidateRect 

• WinlnvalidateRegion 

• WinlsWindowVisible 

• WinLockVisRegions 

• WinOpenWindowDC 

• WinQueryUpdateRect 

• WinQueryUpdateRegion 

• WinRealizePalette 

• WinReleasePS 

• WinShowWindow 

• WinUpdateWindow 

• WinValidateRect 

• WinValidateRegion 
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WinlsWindowShowing  - 
Query  Window  Showing 


Example  Code 

This  example  uses  WinlsWindowShowing  to  check  if  any  part  of  the  window  is  physically  visible 
before  causing  a redraw  of  the  window  via  WinlnvalidateRect. 


fdefine  INCL_WINWINDOWMGR  /*  Window  Manager  Functions  */ 
fdefine  INCL_WINFRAMEMGR  /*  Window  Frame  Functions  */ 
finclude  <os2.h> 


HWND  hwnd;  /*  window  handle 

RECTL  rcl ; /*  update  region 


/*  if  any  part  of  the  window  is  visible,  cause  a redraw  */ 
if  (WinlsWindowShowing(hwnd)) 

{ 

Wi nQueryUpdateRect ( hwnd , &rcl ) ; 


Wi nlnval i dateRect (hwnd , 
&rcl , 

FALSE) ; 

} 


/*  window  to  invalidate  */ 
/*  invalid  rectangle  */ 
/*  do  not  include  children  */ 


*/ 

*/ 
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WinlsWindowVisible  - 
Query  Window  Visibility 


#define  INCL_WINWINDOWMGR  /*  Or  use  INCL_WIN  or  INCL_PM  7 


BOOL  WinlsWindowVisible  (HWND  hwnd) 


This  function  returns  the  visibility  state  of  a window. 

Parameters 

hwnd  (HWND)  - input 
Window  handle. 


Returns 

Visibility-state  indicator: 

TRUE  Window  and  all  its  parents  have  the  WS_VISIBLE  style  bit  set  on 
FALSE  Window  or  one  of  its  parents  have  the  WS_VISIBLE  style  bit  set  off. 

Possible  returns  from  WinGetLastError 

PMERR  INVALID  HWND  An  invalid  window  handle  was  specified. 

Remarks 

Because  fVisible  reflects  only  the  values  of  WS_VISIBLE  style  bits,  fVisible  may  be  set  to  TRUE  even 
if  hwnd  is  totally  obscured  by  other  windows. 


Related  Functions 

• WinBeginPaint 

• WinEnableWindowUpdate 

• WinEndPaint 

• WinExcludeUpdateRegion 

• WinGetClipPS 

• WinGetPS 

• WinGetScreenPS 

• WinlnvalidateRect 

• WinlnvalidateRegion 

• WinlsWindowShowing 

• WinLockVisRegions 

• WinOpenWindowDC 

• WinQueryUpdateRect 

• WinQueryUpdateRegion 

• WinRealizePalette 

• WinReleasePS 

• WinShowWindow 

• WinUpdateWindow 

• WinValidateRect 

• WinValidateRegion 
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WinlsWindowVisible  - 
Query  Window  Visibility 


Example  Code 

This  example  uses  WinlsWindowVisible  to  query  the  visibility  state  of  a window  (i.e.  the  value  of  the 
WS_VISIBLE  style  bits)  when  the  window  is  created,  so  that  the  window  can  be  designated  as  visible, 
if  necessary,  by  calling  WinEnableWindowUpdate. 

fdefine  INCL_WINWINDOWMGR  /*  Window  Manager  Functions  */ 

linclude  <os2.h> 

HWND  hwnd;  /*  parent  window  */ 

BOOL  fSuccess;  /*  success  indicator  */ 

case  WM_CREATE: 

/*  if  window  has  WS_VISIBLE  off,  set  state  to  visible  */ 
if  (!WinIsWindowVisible(hwnd)) 

{ 

/*  set  state  to  visible  and  cause  WMPAINT  message  */ 
fSuccess  = WinEnableWindowUpdate (hwnd,  TRUE); 

} 
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Win  Load  AccelTable  - 
Load  Accelerator  Table 


#define  INCL_WINACCELERATORS  /*  Or  use  INCL_WIN  or  INCL_PM  */ 


HACCEL  W I nLoad AccelTable  (HAB  hab,  HMODULE  Resource,  ULONG  IdAccelTable) 


This  function  loads  an  accelerator  table. 

Parameters 

hab  (HAB)  - input 

Anchor-block  handle. 

Resource  (HMODULE)  - input 

Resource  identity  containing  the  accelerator  table. 

Module  handle  returned  by  the  DosLoadModule  or  DosGetModHandle  functions  referencing  a 
dynamic  link  library  containing  the  resource  or  NULLHANDLE  for  the  application's  module. 

IdAccelTable  (ULONG)  - input 

Accelerator-table  identifier,  within  the  resource  file. 


Returns 

Accelerator-table  handle. 

Possible  returns  from  WinGetLastError 

PMERR  RESOURCE  NOT  FOUND  The  specified  resource  identity  could  not  be  found. 

Remarks 

This  function  returns  a different  value  when  called  twice  in  succession  with  the  same  parameter 
values. 

The  accelerator  table  is  owned  by  the  process  from  which  this  function  is  issued.  It  cannot  be 
accessed  directly  from  any  other  process.  If  it  still  exists  when  the  process  terminates,  it  is 
automatically  deleted  by  the  system. 


Related  Functions 

• WinCopyAccelTable 

• WinCreateAccelTable 

• WinDestroyAccelTable 

• WinQueryAccelTable 

• WinSetAccelTable 

• WinTranslateAccel 
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Load  Accelerator  Table 


Example  Code 

This  example  loads  an  accelerator-table,  using  the  application  defined  accelerator  id,  from  a 
resource  using  the  resource  handle  returned  by  DosLoadModule  or  DosQueryModuleHandle.  The 
returned  table  handle  is  then  used  by  WinCopy AccelTable  to  copy  the  table  into  an  in-memory 
accelerator  table  structure. 

fdefine  INCL_WINACCELERATORS  /*  Window  Accelerator  Functions  */ 


fdefine  INCL_DOSMODULEMGR  /*  Module  Manager  Functions  */ 

finclude  <os2.h> 
fdefine  ACCEL_ID  1 

ULONG  ulCopied;  /*  bytes  copied  */ 

HACCEL  hAccel;  /*  Accelerator-table  handle  */ 

ACCELTABLE  pacct Accel  Table;/*  Accelerator-table  data  area  */ 
ULONG  ulCopyMax;  /*  Maximum  data  area  size  */ 

ULONG  idAccelTable=ACCEL_ID;/*  Accelerator-table  identifier  */ 
HAB  hab;  /*  anchor-block  handle  */ 

HMODULE  hmodDLL;  /*  resource  module  */ 

CHAR  LoadError[10O] ; /*  object  name  buffer  for  DosLoad  */ 

ULONG  rc;  /*  return  code  */ 


/*  obtain  resource  handle  */ 

rc  = DosLoadModule(LoadError,  sizeof (LoadError) , "RES. DLL", 
&hmodDLL) ; 


if  (rc  ==  0) 

hAccel  = WinLoadAccelTable(hab,  hmodDLL,  idAccelTable) ; 

ulCopyMax  = sizeof(pacctAccelTable) ; 
if  (hAccel) 

ulCopied  = Wi nCopyAccelTable( hAccel , &pacct Accel  Table, 

ulCopyMax) ; 
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WinLoadDIg 
Load  Dialog 


#define  INCL_WINDIALOGS  /*  Or  use  INCL_WIN  or  INCL_PM.  Also  in  COMMON  section  7 


HWND  WinLoadDIg  (HWND  hwndParent,  HWND  hwndOwner,  PFNWP  pDigProc, 

HMODULE  Resource,  ULONG  idDigld,  PVOID  pCreateParams) 


This  function  creates  a dialog  window  from  the  dialog  template  idDIgid  in  Resource  and  returns  the 
dialog  window  handle. 

Parameters 

hwndParent  (HWND)  - input 

Parent-window  handle  of  the  created  dialog  window: 

HWND_DESKTOP  The  desktop  window 

HWND_OBJECT  Object  window 

Other  Specified  window. 

hwndOwner  (HWND)  - input 

Requested  owner-window  handle  of  the  created  dialog  window. 

The  actual  owner  window  is  calculated  using  the  algorithm  specified  below. 

pDigProc  (PFNWP)  - input 

Dialog  procedure  for  the  created  dialog  window. 

Resource  (HMODULE)  - input 

Resource  identity  containing  the  dialog  template. 

NULLHANDLE  Use  the  application’s  .EXE  file. 

Other  Module  handle  returned  from  the  DosLoadModule  or  DosGetModHandle 

functions. 

IdDigld  (ULONG)  - input 

Dialog-template  identity  within  the  resource  file. 

It  is  also  used  as  the  identity  of  the  created  dialog  window. 

pCreateParams  (PVOID)  - input 
Application-defined  data  area. 

This  is  passed  to  the  dialog  procedure  in  the  WMJNITDLG  message. 


Returns 

Dialog-window  handle: 

NULL  Dialog  window  not  created 
Other  Dialog  window  handle. 

Possible  returns  from  WinGetLastError 

PMERRINVALIDHWND 

PMERRINVALIDINTEGERATOM 

PMERRINVALIDATOMNAME 

PMERR_ATOM_NAME_NOT_FOUND 

PMERRRESOURCENOTFOUND 


An  invalid  window  handle  was  specified. 

The  specified  atom  is  not  a valid  integer  atom. 

An  invalid  atom  name  string  was  passed. 

The  specified  atom  name  is  not  in  the  atom  table. 
The  specified  resource  identity  could  not  be  found 
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WinLoadDIg  - 
Load  Dialog 


Remarks 

Unless  window  style  WS_VISIBLE  is  specified  for  the  dialog  window  in  the  DIALOG  statement  within 
the  dialog  template,  the  dialog  window  is  created  as  an  invisible  window. 

The  dialog  window  owner  may  be  modified,  in  order  to  ensure  acceptable  results  if  it  is  later 
processed  as  a modal  dialog  using  the  WinProcessDIg  or  WinGetDIgMsg  functions.  A search  is 
made  up  the  parent  hierarchy,  starting  at  the  window  specified  by  the  hwndOwner  parameter,  until  a 
child  of  the  window  specified  by  the  hwndParent  is  found.  If  such  a window  exists,  it  is  made  the 
actual  owner  of  the  dialog.  If  no  such  window  exists  the  actual  owner  of  the  dialog  is  set  to 
NULLHANDLE. 

This  function  returns  immediately  after  creating  the  dialog  window.  A WMJNITDLG  (Default  Dialogs) 
message  is  sent  to  the  dialog  procedure  before  this  function  returns. 

This  function  should  not  be  used  while  pointing  device  capture  is  set  (see  WinSetCapture). 

As  each  of  the  controls  defined  within  the  template  of  this  dialog  window  is  created  during  the 
processing  of  this  function,  the  dialog  procedure  may  receive  various  control  notifications  before  this 
function  returns. 

A dialog  window  can  be  destroyed  with  the  WinDestroyWindow  function. 

Because  windows  are  created  from  the  template,  strings  in  the  template  are  processed  with 
WinSubstituteStrings.  Any  resultant  WM_SUBSTITUTESTRING  messages  are  sent  to  the  dialog 
procedure  before  this  function  returns. 

When  the  child  windows  of  the  dialog  are  created,  the  WinSubstituteStrings  function  is  used  to  allow 
the  child  windows  to  perform  text  substitutions  in  their  window  text.  If  any  of  the  child  window  text 
strings  contain  the  percent  (%)  substitution  character,  there  is  an  upper  limit  of  256  on  the  length  of 
the  text  string,  after  it  is  returned  from  the  substitution. 

If  a dialog  template  (typically  compiled  using  the  resource  compiler)  references  another  resource 
(for  example  an  icon  resource  for  an  icon  static  control),  this  function  always  searches  for  that 
resource  in  the  .EXE  file.  If  an  application  wishes  to  keep  resources  referenced  by  a dialog  template 
in  a .DLL  library,  these  resources  must  be  loaded  by  an  explicit  function  call  during  the  processing  of 
the  WMJNITDLG  message. 

Note:  In  general,  it  is  better  to  create  the  dialog  window  invisible  as  this  allows  for  optimization.  In 
particular,  an  experienced  user  can  type  ahead,  anticipating  the  processing  in  the  dialog 
window. 

In  this  instance,  there  may  be  no  need  to  display  the  dialog  window  at  all,  as  the  user  might 
have  finished  the  interaction  before  the  window  can  be  displayed. 

This  is  in  fact  how  the  WinProcessDIg  function  works;  it  does  not  display  the  dialog  window 
while  there  are  still  WM_CHAR  messages  in  the  input  queue,  but  allows  these  to  be  processed 
first. 

Related  Functions 

• WinCreateDIg 

• WinDefDIgProc 

• WinDismissDIg 

• WinDIgBox 

• WinGetDIgMsg 

• WinProcessDIg 
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WinLoadDIg  - 
Load  Dialog 

Related  Messages 

• WMJNITDLG  (Default  Dialogs) 

• WM_SUBSTITUTESTRING 

• WM_CHAR 


Example  Code 

This  example  uses  WinLoadDIg  to  load  a dialog  template  from  the  application's  .EXE  file. 

fdefine  INCL_WINDIALOGS  /*  Window  Dialog  Mgr  Functions  */ 
finclude  <os2.h> 

HWND  hwndOwner;  /*  owner  window  */ 

HWND  hwndDlg;  /*  Dialog-window  handle  */ 

PFNWP  GenericDlgProc;  /*  dialog  process  */ 

hwndDlg  = WinLoadDlg(HWND_DESKTOP,  /*  parent  is  desk  top  */ 

hwndOwner,  /*  owner  is  main  frame  */ 

GenericDlgProc,  /*  dialog  procedure  */ 

0L,  /*  load  from  resource  file  */ 

DLG_ID,  /*  dialog  resource  id  */ 

NULL);  /*  no  dialog  parameters  */ 
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WinLoadFilelcon  - 
Load  File  Icon 


#define  INCL_WINWORKPLACE 


HPOINTER  WinLoadFilelcon  (PSZ  pszFileName,  BOOL  (Private) 


The  WinLoadFilelcon  function  will  return  a pointer  to  an  icon  which  is  associated  with  the  file 
specified  by  pszFileName. 


Parameters 

pszFileName  (PSZ)  - input 

A pointer  to  a zero-terminated  string  which  contains  the  name  of  the  file  whose  icon  will  be 
loaded. 

(Private  (BOOL)  - input 
Icon  usage  flag: 

TRUE  A private  copy  of  this  icon  is  requested.  This  flag  should  be  used  if  the  application 
needs  to  modify  the  icon. 

FALSE  A shared  pointer  to  this  icon  is  requested.  This  flag  should  be  used  if  application  needs 
to  display  the  icon  without  modifying  it.  This  should  be  used  whenever  possible  to 
optimize  system  resource  use. 

Returns 

Success  indicator: 

NULL  Error  occurred. 

OTHER  Handle  to  an  icon. 

Remarks 

The  icon  will  be  retrieved  in  the  following  order  until  an  icon  has  been  found: 

• .ICON  extended  attribute 

• .ICO  file  in  same  directory  with  same  prefix 

• Application  specific  icon  (if  PM  executable  or  MS  Windows  executable*) 

• PM  application  icon  (if  PM  executable) 

• MS  Windows  application  icon  (if  MS  Windows  application  executable)* 

• OS/2  application  icon  (if  OS/2  full-screen  only  executable  ) 

• OS/2  window  icon  (if  OS/2  window  compatible  executable) 

• DOS  windowed  application  icon  (if  DOS  windowed  executable) 

• Program  application  (if  unknown  type  executable) 

• Data  icon  specified  by  associated  application 

• Data  icon  of  associated  application 

• Data  file  icon  (if  not  program  or  directory) 

• Directory  icon  (if  directory) 

The  HPOINTER  returned  in  fPrivate  should  be  freed  by  the  caller  via  WinFreeFilelcon  when  it  is  no 
longer  being  used. 
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WinLoadFilelcon 
Load  File  Icon 


Related  Functions 

• WinSetFilelcon 

• WinFreeFilelcon 
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WinLoadHelpTable  - 
Load  Help  Table 


#define  INCL_WINHELP  /*  Or  use  INCL_WIN  or  INCL_PM  V 


BOOL  WinLoadHelpTable  (HWND  hwndHelpInstance,  ULONG  IdHelpTable,  HMODULE  Module) 


This  function  identifies  the  module  handle  and  identity  of  the  help  table  to  the  instance  of  the  help 
manager. 

Parameters 

hwndHelpInstance  (HWND)  - input 

Handle  of  an  instance  of  the  help  manager. 

This  is  the  handle  returned  by  the  WinCreateHelpInstance  call. 

IdHelpTable  (ULONG)  - input 
Identity  of  the  help  table. 

Module  (HMODULE)  - input 

Handle  of  the  module  which  contains  the  help  table  and  help  subtable  resources. 


Returns 

Success  indicator: 

TRUE  Successful  completion 
FALSE  Error  occurred. 

Remarks 

An  application  specifies  or  changes  the  handle  of  the  module  which  contains  the  help  table  or  the 
identity  of  the  help  table. 

This  function  corresponds  to  the  HM_LOAD_HELP_TABLE  message  that  identifies  the  identifier  of  a 
help  table  and  the  handle  of  the  module  which  contains  the  help  table  and  its  associated  help 
subtables. 

Related  Functions 

• WinAssociateHelpinstance 

• WinCreateHelpInstance 

• WinCreateHelpTable 

• WinDestroyHelpInstance 

• WinQueryHelpinstance 

Related  Messages 

• HM_LOAD_HELP_TABLE 
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Load  Help  Table 

Example  Code 

BOOL  LoadHelpTable(  HWNO  hWnd,  USHORT  usResource,  PSZ  pszModuleName  ) 

{ 

BOOL  bSuccess  = FALSE; 

HMODULE  hmodule; 

HWND  hwndHel  p ; 

PSZ  pszObjNameBuf [ 80  ]; 

/*  get  the  DLL  loaded  */ 

if(  !DosLoadModule(  pszObjNameBuf,  sizeof(  pszObjNameBuf  ), 
pszModuleName,  &hmodule  ) ) 

{ 

/*  get  the  associated  help  instance  */ 
hwndHel p = WinQueryHelpInstance(  hWnd  ); 

if(  hwndHel p ) 

{ 

/*  pass  address  of  help  table  to  the  help  manager  */ 
bSuccess  = WinLoadHelpTable(  hwndHelp,  usResource,  hmodule  ); 

} 

} 

/*  return  success  indicator  */ 
return  bSuccess; 

} 
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Load  Library 


#define  INCL_WINLOAD  /*  Or  use  INCL_WIN  or  INCL_PM  */ 


HUB  WinLoadLibrary  (HAB  hab,  PSZ  pszLibname) 


This  function  makes  the  library  available  to  the  application. 


Parameters 

hab  (HAB)  - input 

Anchor-block  handle. 

pszLibname  (PSZ)  - input 
Library  name. 


Returns 

Library  handle: 

NULLHANDLE  Library  not  successfully  loaded 
Other  Library  handle. 


Remarks 

This  function  makes  the  library  pszLibname  (containing  procedures,  or  resources,  or  both)  available 
to  the  application.  All  of  the  dynamic  link  libraries  have  the  .DLL  filename  extension  by  default. 


Related  Functions 

• WinDeleteLibrary 

• WinDeleteProcedure 

• WinLoadProcedure 

Example  Code 

This  example  loads  the  RES. DLL  resource/procedure  library,  returning  a library  handle  that  is  then 
used  by  WinLoadProcedure  to  load  procedures  from  that  library. 


fdefine  INCL_WINLOAD  /*  Window  Load  Functions  */ 
finclude  <os2.h> 

PFNWP  pWndproc;  /*  procedure  pointer  */ 
HAB  hab;  /*  anchor-block  handle  */ 
HLIB  hlib;  /*  library  handle  */ 
char  pszLibname[10]="RES.DLL";  /*  library  name  string  */ 
char  pszProcname[10]="WndProc";  /*  procedure  name  string  */ 


/*  load  RES. DLL  */ 

hlib  = WinLoadLibrary (hab,  pszLibname); 

/*  load  WndProc  */ 

pWndproc  = WinLoadProcedure(hab,  hlib,  pszProcname) ; 
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WinLoadMenu 
Load  Menu 


#define  INCL_WINMENUS  /*  Or  use  INCL_WIN  or  INCL_PM  */ 


HWND  WinLoadMenu  (HWND  hwndOwner,  HMODULE  Resource,  ULONG  IdMenuid) 


This  function  creates  a menu  window  from  the  menu  template  idMenuid  from  Resource,  and  returns 
in  hwndMenu  the  window  handle  for  the  created  window. 

Parameters 

hwndOwner  (HWND)  - input 

Owner-  and  parent-window  handle: 

HWND_DESKTOP  The  desktop  window 

HWND  OBJECT  Object  window 

Other  Specified  window. 

Resource  (HMODULE)  - input 
Resource  identifier. 

NULLHANDLE  The  resource  is  in  the  &periodEXE  file  of  the  application. 

Other  The  module  handle  returned  by  the  DosLoadModule  or  DosGetModHandle  call. 

idMenuid  (ULONG)  - input 

Menu  identifier  within  the  resource  file. 


Returns 

Menu-window  handle. 

Remarks 

The  menu  window  is  created  with  its  parent  and  owner  set  to  hwndOwner,  and  with  identity 
FID_MENU.  If  hwndOwner  is  HWND_OBJECT  or  a window  handle  returned  from 
WinQueryObjectWindow,  the  menu  window  is  created  as  an  object  window. 

Action  bar  menus  are  created  as  child  windows  of  the  frame  window  and  are  initially  visible. 
Submenus  are  initially  created  as  object  windows  that  are  owned  by  the  window  frame. 


Related  Functions 

• WinCreateMenu 

• WinPopupMenu 
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Load  Menu 


Example  Code 

This  example  creates  a menu  window  from  the  menu  template  (idMenuld)  located  in  'RES. DLL'  and 
returns  a menu  handle  which  is  used  by  WinPopupMenu. 


fdefine  INCL_WINWINDOWMGR  /*  Window  Manager  Functions 

fdefine  INCL_WINMENUS  /*  Window  Menu  Functions 

finclude  <os2.h> 


HWND  hwndMenu; 

HWND  tiwndOwner; 
HMODULE  hmodDLL; 
ULONG  idMenuid; 
BOOL  f Success; 

HWND  hwndParent; 

ULONG  fl Options; 


/*  menu  window 
/*  owner  window 
/*  resource  handle 
/*  resource  menu  id 
/*  success  indicator 
/*  parent  window 
/*  pop-up  menu  options 


i f (DosQueryModul eHandl e ( "RES . DLL" , &hmodDLL) ) 

hwndMenu  = WinLoadMenu(hwndOwner,  hmodDLL,  idMenuid); 


*/ 

*/ 


*/ 

*/ 

*/ 

*/ 

*/ 

*/ 

*/ 


fl Options  = PU_M0USEBUTT0N1D0WN  | PU_KEYBOARD  | PU_M0USEBUTT0N1; 
f Success  = WinPopupMenu (hwndParent,  hwndOwner,  hwndMenu,  0,  50, 
0,  flOptions); 
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Load  Message 


#define  INCL_WINWINDOWMGR  /*  Or  use  INCL_WIN  or  INCL_PM  */ 


LONG  WinLoadMessage  (HAB  hab,  HMODULE  hmodMod,  ULONG  ulld,  LONG  IcchMax, 
PSZ  pszBuffer) 


This  function  loads  a message  from  a resource,  copies  the  message  to  the  specified  buffer,  and 
appends  a terminating  null  character. 


Parameters 

hab  (HAB)  - input 

Anchor-block  handle. 

hmodMod  (HMODULE)  - input 
Module  handle. 

ulld  (ULONG)  - input 
Message  identifier. 

IcchMax  (LONG)  - input 

Specifies  the  size  of  buffer. 

pszBuffer  (PSZ)  - input 

Points  to  the  buffer  that  receives  the  message 


Returns 

The  length  of  the  string  returned. 

This  excludes  the  terminating  null,  and  has  the  following  values: 

0 Error 

Other  A maximum  value  of  {IcchMax—  1). 

Remarks 

Message  resources  contain  up  to  16  messages  each.  The  resource  ID  is  calculated  from  the  id 
parameter  value  passed  to  this  function  as  follows: 

resource  ID  = (id  / 16)  + 1 

To  save  storage  on  disk  and  in  memory,  applications  should  number  their  message  resources 
sequentially,  starting  at  some  multiple  of  16. 

Related  Functions 

• WinLoadString 
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WinLoadMessage  - 
Load  Message 


Example  Code 

This  example  loads  an  error  message  from  ERR. DLL  using  the  resource  handle  from 
DosLoadModule  and  uses  the  message  in  a message  box. 


fdefine  INCL_WINWINDOWMGR  /*  Window  Manager  Functions  */ 

fdefine  INCL_DOSMODULEMGR  /*  Module  Manager  Functions  */ 

fdefine  INCL_WINDIALOGS  /*  Window  Dialog  Mgr  Functions  */ 

finclude  <os2.h> 
fdefine  ERRMSG_ID  1 

LONG  1 Length;  /*  length  of  string  */ 

HAB  hab;  /*  anchor-block  handle  */ 

HMODULE  hmodDLL;  /*  Handle  of  resource  module  */ 

LONG  lBufferMax  = 100;/*  Size  of  buffer  */ 

char  pszErrMsg[lO0] ; /*  error  message  */ 

CHAR  LoadError[lO0] ; /*  object  name  buffer  for  DosLoad  */ 

ULONG  rc;  /*  return  code  */ 

HWND  hwnd;  /*  window  handle  */ 


/*  obtain  resource  handle  */ 

rc  = DosLoadModule(LoadError,  sizeof(LoadError) , "ERR. DLL", 
&hmodDLL) ; 

/*  load  message  from  resource  */ 
if  (rc  ==  0) 

{ 

/*  load  error  message  string  */ 

1 Length  = WinLoadMessage(hab,  hmodDLL,  ERRMSG_ID,  lBufferMax, 

pszErrMsg) ; 


/*  display  error  message  box  */ 
Wi nMessageBox ( HWND_DESKTOP , 
hwnd, 

pszErrMsg, 

"Error  message", 

0, 

MB_N0IC0N  | MB_0K) ; 


/*  client-window  handle  */ 
/*  message  */ 
/*  title  of  the  message  */ 
/*  message  box  id  */ 
/*  icon  and  button  flags  */ 


Chapter  8.  Window  Functions  8-247 


WinLoadPointer 
Load  Pointer 


#define  INCL_WINPOINTERS  /*  Or  use  INCL_WIN  or  INCL_PM  */ 


HPOINTER  WinLoadPointer  (HWND  hwndDeskTop,  HMODULE  Resource,  ULONG  idPointer) 


This  function  loads  a pointer  from  a resource  file  into  the  system. 


Parameters 

hwndDeskTop  (HWND)  - input 
Desktop- window  handle: 

HWND_DESKTOP  The  desktop  window 

Other  Desktop-window  handle  returned  by  WinQueryDesktopWindow. 

Resource  (HMODULE)  - input 

Resource  identity  containing  the  pointer  definition. 

NULLHANDLE  Use  the  resources  file  for  the  application. 

Other  Module  handle  returned  by  the  DosLoadModule  or  DosGetModHandle  call 

referencing  a dynamic-link  library  containing  the  resource. 

IdPointer  (ULONG)  - input 

Identifier  of  the  pointer  to  be  loaded. 


Returns 

Pointer  handle: 

NULLHANDLE  Error  has  occurred 
Other  Handle  of  loaded  pointer. 

Possible  returns  from  WinGetLastError 

PMERRINVALIDHWND 
PMERRRESOURCENOTFOUND 

Remarks 

A new  copy  of  the  pointer  is  created  each  time  this  function  is  called.  The  pointer  created  by  this 
function  can  be  destroyed  using  the  WinDestroyPointer  function.  To  get  one  of  the  standard  system 
pointers,  use  the  WinQuerySysPointer  function. 

The  pointer  is  owned  by  the  process  from  which  this  function  is  issued.  It  cannot  be  accessed 
directly  from  any  other  process.  If  it  still  exists  when  the  process  terminates,  it  is  automatically 
deleted  by  the  system. 


An  invalid  window  handle  was  specified. 

The  specified  resource  identity  could  not  be  found. 
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WinLoadPointer  - 
Load  Pointer 


Related  Functions 

• WinCreatePointer 

• WinCreatePointerlndirect 

• WinDestroyPointer 

• WinDrawPointer 

• WinQueryPointer 

• WinQueryPointerlnfo 

• WinQueryPointerPos 

• WinQuerySysPointer 

• WinSetPointer 

• WinSetPointerPos 

• WinShowPointer 

Example  Code 

This  example  calls  WinLoadPointer  to  load  an  application  defined  pointer.  When  processing  the 
WM_MOUSEMOVE  message,  the  loaded  pointer  is  displayed  by  calling  WinSetPointer. 

Idefine  INCL_WINPOINTERS  /*  Window  Pointer  Functions  */ 

finclude  <os2.h> 

HPOINTER  hptrCrossHair;/*  pointer  handle  */ 

case  WM_CREATE: 

hptrCrossHair  = WinLoadPointer(HWND_DESKTOP, 

OL,  /*  load  from  .exe  file  */ 

IDP_CROSSHAIR) ; /*  identifies  the  pointer  */ 

case  WM_M0USEM0VE: 

WinSetPointer(HWND_DESKTOP,  hptrCrossHair) ; 
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WinLoadProcedure  - 
Load  Procedure 


#define  INCL_WINLOAD  /*  Or  use  INCL_WIN  or  INCL_PM  7 


PFNWP  WinLoadProcedure  (HAB  hab,  HUB  hllbLibhandle,  PSZ  pszProcname) 


This  function  loads  the  window  or  dialog  procedure  from  a specified  dynamic  link  library. 


Parameters 

hab  (HAB)  - input 

Anchor-block  handle. 

hllbLibhandle  (HUB)  - input 
Library  handle. 

pszProcname  (PSZ)  - input 
Procedure  name. 


Returns 

Window-procedure  identifier: 

NULL  Procedure  not  successfully  loaded 
Other  Window-procedure  identifier. 

Remarks 

This  function  loads  the  window  or  dialog  procedure  pszProcname  from  the  library  hlibLibhandle. 


Related  Functions 

• WinDeleteLibrary 

• WinDeleteProcedure 

• WinLoadLibrary 

Example  Code 

This  example  loads  the  WndProc  procedure,  returning  a pointer  to  the  procedure,  from  the  RES. DLL 
library,  based  on  the  library  handle  returned  by  WinLoadLibrary. 


fdefine  INCL_WINLOAD  /*  Window  Load  Functions  */ 
finclude  <os2.h> 

PFNWP  pWndproc;  /*  procedure  pointer  */ 
HAB  hab;  /*  anchor-block  handle  */ 
HLIB  hlib;  /*  library  handle  */ 
char  pszLibname[10]="RES.DLL";  /*  library  name  string  */ 
char  pszProcname [10] ="WndProc";  /*  procedure  name  string  */ 


/*  load  RES. DLL  */ 

hlib  = WinLoadLibrary(hab,  pszLibname); 

/*  load  WndProc  */ 

pWndproc  = WinLoadProcedure(hab,  hlib,  pszProcname); 
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WinLoadString  - 
Load  String 


#define  INCL.WINWINDOWMGR  /*  Or  use  INCL_WIN  or  INCL_PM  */ 


LONG  WinLoadString  (HAB  hab,  HMODULE  Resource,  ULONG  IdStrlng,  LONG  IBufferMax, 
PSZ  pszBuffer) 


This  function  loads  a string  from  a resource. 


Parameters 

hab  (HAB)  - input 

Anchor-block  handle. 

Resource  (HMODULE)  - input 

Resource  identity  containing  the  string. 

NULLHANDLE  Use  the  application's  own  resources  file. 

Other  Module  handle  returned  by  the  DosLoadModule  or  DosGetModHandle  call 

referencing  a dynamic-link  library  containing  the  resource. 

IdStrlng  (ULONG)  - input 
String  identifier. 

IBufferMax  (LONG)  - input 
Size  of  buffer. 

pszBuffer  (PSZ)  - output 

Buffer  that  is  to  receive  the  string. 


Returns 

The  length  of  the  string  returned. 

This  excludes  the  terminating  null,  and  has  the  following  values: 

0 Error 

Other  A maximum  value  of  {IBufferMax—  1). 

Possible  returns  from  WinGetLastError 

PMERRRESOURCENOTFOUND  The  specified  resource  identity  could  not  be  found. 

Remarks 

This  function  loads  a string  resource  identified  by  the  idString  and  the  Resource  parameters  into  the 
pszBuffer  parameter,  and  appends  a terminating  null  character. 

RT_STRING  resources  (string  resources)  contain  up  to  16  strings  each  (see  “Resource  ( RES)  File 
Specification”  on  page  32-27).  The  resource  ID  is  calculated  from  the  idString  passed  to  this 
function  as  follows: 

resource  ID  = (idString  / 16)  + 1 

To  save  storage  on  disk  and  in  memory,  applications  should  number  their  string  resources 
sequentially,  starting  at  some  multiple  of  16. 
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Win  LoadString 
Load  String 


Related  Functions 

• WinCompareStrings 

• WinNextChar 

• WinPrevChar 

• WinSubstituteStrings 

• WinUpper 

• WinUpperChar 

Example  Code 

This  example  loads  a string  from  RES.DLL  using  the  resource  handle  from  DosLoadModule. 


Idefine  INCL_WINWINDOWMGR  /*  Window  Manager  Functions  */ 
Idefine  INCL_DOSMODULEMGR  /*  Module  Manager  Functions  */ 
linclude  <os2.h> 

Idefine  STRING_ID  1 

LONG  1 Length;  /*  length  of  string  */ 
HAB  hab;  /*  anchor-block  handle  */ 
HMODULE  hmodDLL;  /*  Handle  of  resource  module  */ 
ULONG  idString  = STRING_ID;  /*  String  identifier  */ 
LONG  lBufferMax  = 10;/*  Size  of  buffer  */ 
char  pszStringl[10] ; /*  first  string  */ 
CHAR  LoadError[100] ; /*  object  name  buffer  for  OosLoad  */ 
ULONG  rc;  /*  return  code  */ 


/*  obtain  resource  handle  */ 

rc  = DosLoadModule(LoadError,  sizeof(LoadError) , "RES.DLL", 
&hmodDLL) ; 

/*  load  string  from  resource  */ 
if  (rc  ==  0) 

1 Length  = WinLoadString(hab,  hmodDLL,  idString,  lBufferMax, 

pszStringl) ; 
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WinLockVisRegions  - 
Lock  Visible  Regions 


#define  INCL_WINWINDOWMGR  /*  Or  use  INCL_WIN  or  INCL_PM  */ 


BOOL  WinLockVisRegions  (HWND  hwndDeskTop,  BOOL  (Lock) 


This  function  locks  or  unlocks  the  visible  regions  of  all  the  windows  on  the  screen,  preventing  any  of 
the  visible  regions  from  changing. 


Parameters 

hwndDeskTop  (HWND)  - input 

Desktop-window  handle  or  HWND_DESKTOP. 

fLock  (BOOL)  - input 

Indicates  whether  the  visible  regions  are  being  locked  or  unlocked: 

TRUE  Lock  the  visible  regions 
FALSE  Unlock  the  visible  regions. 


Returns 

Success  indicator. 

TRUE  Successful. 

FALSE  Error  occurred. 

Possible  returns  from  WinGetLastError 

PMERR  INVALID  HWND  An  invalid  window  handle  was  specified. 

Remarks 

This  function  is  useful  to  threads  that  need  to  prevent  window  visible  regions  from  changing  while 
some  screen  operation,  such  as  copying  screen  pels  into  a memory  bit  map,  is  being  performed. 

Any  other  thread  that  tries  to  alter  the  visible  regions  is  blocked  while  the  visible  regions  are  locked. 
While  the  visible  regions  are  locked,  no  messages  must  be  sent  and  no  functions  called  that  can 
send  messages. 

Only  one  thread  can  lock  the  visible  regions  at  any  one  time.  The  same  thread  can  call 
WinLockVisRegions  multiple  times.  A lock  count  is  maintained  by  the  system  and  is  incremented 
each  time  a locking  call  is  made,  and  decremented  each  time  an  unlocking  call  is  made.  The  visible 
regions  are  unlocked  when  the  count  is  zero. 

Note:  Locking  the  visible  regions  does  not  prevent  painting  of  a window  by  another  process. 
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WinLockVisRegions 
Lock  Visible  Regions 


Related  Functions 

• WinBeginPaint 

• WinEnableWindowllpdate 

• WinEndPaint 

• WinExcludellpdateRegion 

• WinGetClipPS 

• WinGetPS 

• WinGetScreenPS 

• WinlnvalidateRect 

• WinlnvalidateRegion 

• WinlsWindowShowing 

• WinlsWindowVisible 

• WinOpenWindowDC 

• WinQueryllpdateRect 

• WinQueryUpdateRegion 

• WinRealizePalette 

• WinReleasePS 

• WinShowWindow 

• WinUpdateWindow 

• WinValidateRect 

• WinValidateRegion 

Example  Code 

This  example  uses  WinLockVisRegions  to  prevent  any  window's  visible  region  from  changing  while 
a screen  operation  is  executing.  WinLockVisRegions  is  called  before  the  screen  operation  to  lock 
the  visible  regions  and  again  after  the  operation  to  unlock  the  regions. 

fdefine  INCL_WINWINDOWMGR  /*  Window  Manager  Functions  */ 

linclude  <os2.h> 

BOOL  f Success;  /*  success  indicator  */ 

/*  lock  visible  regions  */ 

f Success  = Wi nLockVi sReg i ons ( HWND_DESKTOP , TRUE); 

/* 

. executing  screen  operation 
*/ 

/*  unlock  visible  regions  */ 

fSuccess  = Wi nLockVi sRegi ons (HWND_DESKTOP,  FALSE); 
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WinLockWindowllpdate  - 
Lock  Window  Update 


#define  INCL_WINWINDOWMGR  /*  Or  use  INCL_WIN  or  INCL_PM  7 


BOOL  WinLockWindowUpdate  (HWND  hwndDeskTop,  HWND  hwndLockUpdate) 


This  function  disables  or  enables  output  to  a window  and  its  descendants. 


Parameters 

hwndDeskTop  (HWND)  - input 

Desktop  handle  of  the  screen  containing  the  window  to  be  locked: 

HWND  DESKTOP  The  desktop-window  handle 

Other  Specified  desktop-window  handle. 

hwndLockUpdate  (HWND)  - input 

Handle  of  window  in  which  output  is  to  be  prevented: 

NULLHANDLE  Enable  output  in  the  locked  window  and  its  descendants. 

Other  Handle  of  the  window  in  which  output  is  to  be  prevented.  Output  is  also 

prevented  in  the  descendants  of  the  window. 


Returns 

Success  indicator: 

TRUE  Successful  operation. 

FALSE  Error  occurred. 

Remarks 

This  function  is  used  by  threads  that  need  to  draw  on  an  area  of  the  screen  over  which  they  have  no 
control.  For  example,  the  user  interface  sizing  and  moving  calls  use  this  call  when  drawing  the 
shadow  box,  as  a window  is  sized  or  moved. 

All  threads  continue  to  run  while  the  window  is  disabled;  only  output  is  prevented. 

If  one  thread  disables  the  window,  other  threads  using  this  function  are  blocked  until  the  first  enables 
the  window,  although  they  can  still  receive  messages. 

This  function  does  not  prevent  screen  group  switches,  because  these  may  be  necessary  to  handle 
“hard  errors”  in  other  screen  groups. 
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WinLockWindowUpdate 
Lock  Window  Update 


Example  Code 

This  example  disables  output  to  a window  and  its  children  during  a move  operation  (WM_MOVE)  and 
then  re-enables  output  once  the  move  is  finished. 

Idefine  INCL_WINWINDOWMGR  /*  Window  Manager  Functions  */ 

linclude  <os2.h> 

HWND  hwndLock;  /*  handle  of  window  to  be  (un) locked  */ 

BOOL  fSuccess;  /*  success  indicator  */ 

case  WM_M0VE: 

/*  lock  output  */ 

fSuccess  = WinLockWindowUpdate(HWND_DESKTOP,  hwndLock); 

/* 

. execute  window  move 


V 

/*  unlock  output  */ 

fSuccess  = WinLockWindowUpdate(HWND_DESKTOP,  NULLHANDLE); 
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WinMakePoints  - 
Make  Points 


#define  INCL_WINRECTANGLES  /*  Or  use  INCL_WIN  or  INCL_PM  */ 


BOOL  WinMakePoints  (HAB  hab,  PWPOINT  pwptppt,  ULONG  ccount) 


This  function  converts  points  to  graphics  points. 

Parameters 

hab  (HAB)  - input 

Anchor-block  handle. 

pwptppt  (PWPOINT)  - input/output 
Points  to  be  converted. 

The  data  type  of  these  points  after  conversion  is  POINTL. 

ccount  (ULONG)  - input 

Number  of  points  to  be  converted. 

Must  be  positive. 

Returns 

Success  indicator: 

TRUE  Successful  completion 
FALSE  Error  occurred. 


Remarks 

This  function  converts  the  array  of  points  from  a WPOINT  data  structure  into  a POINTL  data  structure. 

Example  Code 

This  example  calls  WinMakePoints  to  convert  a 3-element  array  of  points  from  window  points 
(WPOINT  structure)  to  graphics  points  (POINTL  structure). 

Idefine  I NCL_WIN.RECT ANGLES  /*  Window  Rectangle  Functions  */ 

finclude  <os2.h> 

HAB  hab;  /*  anchor-block  handle  */ 

BOOL  fSuccess;  /*  success  indicator  */ 

/*  array  of  window  points  */ 

WPOINT  pwptppt [3]  = {0,0,0,0,20,0,50,0,100,0,60,0}; 

/*  convert  points  */ 

fSuccess  = WinMakePoints (hab,  pwptppt,  3); 
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WinMakeRect  - 
Make  Rectangle 


#define  INCL_WINRECTANGLES  /*  Or  use  INCL_WIN  or  INCL_PM  */ 


BOOL  WinMakeRect  (HAB  hab,  PWRECT  pwrcprc) 


This  function  converts  a rectangle  to  a graphics  rectangle. 


Parameters 

hab  (HAB)  - input 

Anchor-block  handle. 

pwrcprc  (WRECT)  - input/output 
Rectangle  to  be  converted. 

The  data  type  of  the  rectangle  after  conversion  is  RECTL. 


Returns 

Success  indicator: 

TRUE  Successful  completion 
FALSE  Error  occurred. 

Remarks 

This  function  converts  a rectangle  from  a WRECT  data  structure  into  a RECTL  data  structure. 


Related  Functions 

• WinCopyRect 

• WinEqualRect 

• WinFillRect 

• WinlnflateRect 

• WinlntersectRect 

• WinlsRectEmpty 

• WinOffsetRect 

• WinPtlnRect 

• WinSetRect 

• WinSetRectEmpty 

• WinSubtractRect 

• WinUnionRect 

Example  Code 

This  example  calls  WinMakeRect  to  convert  a window  rectangle  (WRECT  structure)  to  a graphics 
rectangle  (RECTL  structure). 

fdefine  INCL_WINRECTANGLES  /*  Window  Rectangle  Functions  */ 
linclude  <os2.h> 

HAB  hab;  /*  anchor-block  handle  */ 

BOOL  f Success;  /*  success  indicator  */ 

/*  window  rectangle  */ 

WRECT  pwrcprc  = {0,0,0,0,50,0,50,0}; 

/*  convert  rectangle  */ 

fSuccess  = WinMakeRect(hab,  Spwrcprc); 
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WinMapDIgPoints  - 
Map  Dialog  Points 


#define  INCL_WINDIALOGS  /*  Or  use  INCL_WIN  or  INCL_PM  */ 


BOOL  WinMapDIgPoints  (HWND  hwndDIg,  PPOINTL  aptIPoInts,  ULONG  ulCount, 
BOOL  fOptlons) 


This  function  maps  points  from  dialog  coordinates  to  window  coordinates,  or  from  window 
coordinates  to  dialog  coordinates. 


Parameters 

hwndDIg  (HWND)  - input 
Dialog-window  handle. 

aptIPoInts  (PPOINTL)  - input/output 
Coordinate  points  to  be  mapped. 

The  mapped  points  are  substituted. 

ulCount  (ULONG)  - input 

Number  of  coordinate  points. 

fOptlons  (BOOL)  - input 
Calculation  control: 

TRUE  The  points  are  in  dialog  coordinates  and  are  to  be  mapped  into  window  coordinates 
relative  to  the  window  specified  by  the  hwndDIg  parameter. 

FALSE  The  points  are  in  window  coordinates  relative  to  the  window  specified  by  the  hwndDIg 
parameter  and  are  to  be  mapped  into  dialog  coordinates. 


Returns 

Coordinates-mapped  indicator: 

TRUE  Coordinates  successfully  mapped 
FALSE  Coordinates  not  successfully  mapped. 

Possible  returns  from  WinGetLastError 

PMERR  INVALID  HWND  An  invalid  window  handle  was  specified. 

Related  Functions 

• WinMapWindowPoints 

Example  Code 

This  example  calls  WinMapDIgPoints  to  map  a point  from  dialog  coordinates  to  window  coordinates 
relative  to  the  dialog  window. 

fdefine  INCL_WINDIALOGS  /*  Window  Dialog  Mgr  Functions  */ 

linclude  <os2.h> 

HWND  hwndDIg;  /*  handle  of  dialog  window  */ 

BOOL  f Success;  /*  success  indicator  */ 

POINTL  aptlPoint;  /*  point  to  be  mapped  */ 

/*  map  point  to  relative  window  coordinates  */ 
f Success  = WinMapDIgPoints (hwndDIg,  &aptl Point,  1,  TRUE); 
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WinMapWindowPoints  - 
Map  Window  Points 


#define  INCL_WINWINDOWMGR  /*  Or  use  INCL_WIN  or  INCL_PM  */ 


BOOL  WinMapWindowPoints  (HWND  hwndFrom,  HWND  hwndTo,  PPOINTL  aptIPoints, 

LONG  ICount) 


This  function  maps  a set  of  points  from  a coordinate  space  relative  to  one  window  into  a coordinate 
space  relative  to  another  window. 

Parameters 

hwndFrom  (HWND)  - input 

Handle  of  the  window  from  whose  coordinates  points  are  to  be  mapped: 

HWND_DESKTOP  Points  are  mapped  from  screen  coordinates 
Other  Points  are  mapped  from  window  coordinates. 

hwndTo  (HWND)  - input 

Handle  of  the  window  to  whose  coordinates  points  are  to  be  mapped: 

HWND_DESKTOP  Points  are  mapped  into  screen  coordinates 

Other  Points  are  mapped  into  window  coordinates. 

aptIPoints  (PPOINTL)  - input/output 

Points  to  be  mapped  to  the  new  coordinate  system. 

ICount  (LONG)  - input 

Number  of  points  to  be  mapped. 

aptIPoints  can  be  a RECTL  structure,  in  which  case  this  parameter  should  have  the  value  2. 
Note:  This  is  not  supported  in  all  languages. 

Returns 

Success  indicator: 

TRUE  Successful  completion 
FALSE  Error  occurred. 

Possible  returns  from  WinGetLastError 

PMERRJNVALID  HWND  An  invalid  window  handle  was  specified. 

Related  Functions 

• WinMapDIgPoints 
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WinMapWindowPoints  - 
Map  Window  Points 


Example  Code 

This  example  calls  WinMapWindowPoints  to  map  a mouse  point  on  the  desktop  window  to  a mouse 
point  in  the  client  window  and  then  checks  whether  the  mouse  pointer  is  inside  the  client  area  or  not. 


fdefine  INCLJIINWINDOWMGR  /*  Window  Manager  Functions  */ 
fdefine  INCL_WINRECTANGLES  /*  Window  Rectangle  Functions  */ 
fdefine  INCL_WINPOINTERS  /*  Window  Pointer  Functions  */ 
finclude  <os2.h> 

HAB  hab;  /*  anchor-block  handle  */ 
HWND  hwndClient;  /*  handle  of  client  window  */ 
BOOL  f Success;  /*  success  indicator  */ 
POINTL  ptlMouse;  /*  mouse  pointer  position  */ 
RECTL  rclWork;  /*  client  area  */ 


/*  get  current  mouse  pointer  position  */ 
WinQueryPointerPos(HWND_DESKTOP,  &ptl Mouse) ; 

/*  map  from  desktop  to  client  window  */ 

fSuccess  = WinMapWindowPoints(HWND_DESKTOP,  hwndClient, 

&ptlMouse,  1); 

/*  check  if  new  mouse  position  is  inside  the  client  area  */ 
WinQueryWindowRect(hwndCl ient,  SrclWork) ; 
if  (WinPtInRect(hab,  &rclWork,  &ptlMouse)) 

{ 

/*  pointer  is  in  client  area  */ 

} 
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WinMessageBox 
Message  Box 


#define  INCL_WINDIALOGS  /*  Or  use  INCL_WIN  or  INCL_PM.  Also  in  COMMON  section  */ 

USHORT  WinMessageBox  (HWND  hwndParent,  HWND  hwndOwner,  PSZ  pszText, 

PSZ  pszTItle,  USHORT  usWIndow,  ULONG  fIStyle) 

This  function  creates,  displays,  and  operates  a message  box  window. 

Parameters 

hwndParent  (HWND)  - input 

Parent-window  handle  of  the  created  message-box  window: 

HWND_DESKTOP  The  message  box  is  to  be  main  window 
Other  Parent-window  handle. 

hwndOwner  (HWND)  - input 

Requested  owner-window  handle  of  the  created  message-box  window. 

The  actual  owner  window  is  calculated  using  the  algorithm  specified  in  the  description  of  the 
WinLoadDIg  function. 

pszText  (PSZ)  - input 

Message-box  window  message. 

The  text  of  the  message  to  be  displayed  within  the  message-box  window.  If  multiple  lines  are 
required,  carriage-return  characters  must  be  inserted  into  the  text  at  appropriate  points. 

pszTitle  (PSZ)  - input 

Message-box  window  title: 

The  text  for  the  title  should  not  be  longer  than  40  characters.  If  text  longer  than  this  is  supplied, 
text  centering  is  still  performed,  even  though  the  beginning  and  end  of  the  string  are  not  visible. 

NULL  The  text  Error  is  to  be  displayed  as  the  title  of  the  message-box  window. 

Other  The  text  to  be  displayed  as  the  title  of  the  message-box  window. 

usWIndow  (USHORT)  - input 
Message-box  window  identity. 

This  value  is  passed  to  the  HKJHELP  hook  if  the  WM  HELP  message  is  received  by  the 
message-box  window. 

fIStyle  (ULONG)  - input 

Message-box  window  style. 

These  values  may  be  combined  using  the  logical-OR  operation  but  only  one  value  can  be  taken 
from  each  of  the  following  groups: 

Button  or  Button  Group 

MB_OK  Message  box  contains  an  OK  pushbutton. 

MB_OKCANCEL  Message  box  contains  both  OK  and  CANCEL  pushbuttons. 

MB_CANCEL  Message  box  contains  a CANCEL  pushbutton. 

MB_ENTER  Message  box  contains  an  ENTER  pushbutton. 

MB_ENTERCANCEL  Message  box  contains  both  ENTER  and  CANCEL  pushbuttons. 

MB_RETRYCANCEL  Message  box  contains  both  RETRY  and  CANCEL  pushbuttons. 

MB_ABORTRETRYIGNORE  Message  box  contains  ABORT,  RETRY,  and  IGNORE  pushbuttons. 

MB  YESNO  Message  box  contains  both  YES  and  NO  pushbuttons. 
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M BYESNOC  ANCEL 

Help  button 
MB_HELP 


Color  or  Icon 
MB_NOICON 
MBICONHAND 
MBJCONQUESTION 
M B JCONEXCL  AM  ATION 
MB  ICON  ASTERISK 
M B INFORM  ATION 
MB  QUERY 
MB_WARNING 
MBERROR 

Default  action 
M BDEFBUTTON1 

MBDEFBUTTON2 
M BDEFBUTTON3 

Modality  Indicator 
MB_APPLMODAL 

MBSYSTEMMODAL 

Mobility  Indicator 
MB_MOVEABLE 


WinMessageBox  - 
Message  Box 

Message  box  contains  YES,  NO,  and  CANCEL  pushbuttons. 


Message  box  contains  a HELP  pushbutton. 

When  this  is  selected  a WMHELP  message  is  sent  to  the  window 
procedure  of  the  message  box. 


Message 

Message 

Message 

Message 

Message 

Message 

Message 

Message 

Message 


box  is  not  to  contain  an  icon. 

box  contains  a hand  icon. 

box  contains  a question  mark  (?)  icon. 

box  contains  an  exclamation  point  (!)  icon. 

box  contains  an  asterisk  (*)  icon. 

box  contains  a black  information  ‘i’  in  a square  box. 

box  contains  a question  mark  in  a square  box. 

box  contains  a black  T in  a square  box. 

box  contains  a STOP  sign  on  a white  background. 


The  first  button  is  the  default  selection.  This  is  the  default  case,  if  none 
of  MB_DEFBUTTON1,  MB_DEFBUTTON2,  and  MB_DEFBUTTON3  is 
specified. 

The  second  button  is  the  default  selection. 

The  third  button  is  the  default  selection. 


Message  box  is  application  modal.  This  is  the  default  case.  Its  owner 
is  disabled;  therefore,  do  not  specify  the  owner  as  the  parent  if  this 
option  is  used. 

Message  box  is  system  modal. 


Message  box  is  moveable. 

The  message  box  is  displayed  with  a title  bar  and  a system  menu, 
which  shows  only  the  Move,  Close,  and  Task  Manager  choices,  which 
can  be  selected  either  by  use  of  the  pointing  g device  or  by 
accelerator  keys. 

If  the  user  selects  Close,  the  message  box  is  removed  and  the 
usResponse  is  set  to  MBID_CANCEL,  whether  or  not  a cancel  button 
existed  within  the  message  box. 
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WinMessageBox 
Message  Box 


Returns 


User-response 

value: 

MBID_ENTER 

ENTER  pushbutton  was  selected 

MBIDOK 

OK  pushbutton  was  selected 

MBIDCANCEL 

CANCEL  pushbutton  was  selected 

MBID_  ABORT 

ABORT  pushbutton  was  selected 

MBIDRETRY 

RETRY  pushbutton  was  selected 

M BID  IGNORE 

IGNORE  pushbutton  was  selected 

MBID_YES 

YES  pushbutton  was  selected 

MBIDNO 

NO  pushbutton  was  selected 

MBIDERROR 

Function  not  successful;  an  error  occurred. 

Possible  returns  from  WinGetLastError 

PMERR  INVALID  HWND  An  invalid  window  handle  was  specified. 

PMERR_INVALID_FLAG  An  invalid  bit  was  set  for  a parameter.  Use  constants 

defined  by  PM  for  options,  and  do  not  set  any  reserved 
bits. 


Remarks 

The  message  box  consists  of  a message  and  a simple  dialog  with  the  user. 

This  function  behaves  in  a similar  way  to  WinDIgBox,  and  the  remarks  concerning  modality  which 
are  documented  under  that  call,  and  also  under  the  WinLoadDIg  and  WinProcessDIg  functions,  also 
apply  here. 

This  function  should  not  be  used  while  pointing  device  capture  is  set  (see  WinSetCapture). 

If  the  keyboard  is  used  to  cycle  from  one  window  to  the  next,  the  message  box  and  its  parent  window 
are  considered  to  be  next  to  each  other  in  the  sequence. 

If  a message  box  is  created  as  part  of  the  processing  of  a dialog  window,  where  the  dialog  window 
has  not  been  dismissed,  the  dialog  window  should  be  made  the  owner  of  the  message  box  window. 

If  a system  modal  message  box  is  created  to  indicate  to  the  user  that  the  system  is  running  out  of 
memory,  the  strings  passed  into  this  call  must  not  be  taken  from  a resource  file,  as  an  attempt  to 
load  the  resource  file  could  fail  because  of  the  lack  of  memory.  However,  such  a message  box  can 
safely  use  the  hand  icon  because  this  icon  is  always  memory-resident. 

The  size  of  the  message  box  is  determined  as  follows: 

• The  minimum  width  of  a message  box  is  enough  to  display  40  characters  of  average  width. 

• The  minimum  height  of  a message  box  is  enough  to  display  2 lines. 

* The  text  of  a message  box  is  word-wrapped  by  default.  If  more  than  two  lines  are  required  to 
display  the  text,  the  height  of  the  message  box  is  increased  up  to  a maximum  of  two  thirds  of  the 
screen  height.  The  height  of  a message  box  can  never  exceed  this  value. 

* If  necessary,  the  width  of  a message  box  is  increased  to  allow  room  to  display  the  title. 

Text  is  wrapped  at  word  boundaries  (spaces).  If  a word  is  too  big  to  fit  on  one  line,  the  start  of  the 
word  is  not  wrapped  to  the  next  line,  but  stays  adjacent  to  the  text  it  follows,  and  the  word  is  split  at 
the  box  boundary. 

The  message  box  is  centered  on  the  screen. 
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WinMessageBox  - 
Message  Box 


If  a message  box  window  has  a CANCEL  button,  the  MBID_CANCEL  value  is  returned  if  either  the 
Escape  or  Cancel  keys  are  pressed.  If  the  message  box  window  has  no  CANCEL  button,  pressing  the 
Escape  key  has  no  effect. 


Example  Code 

This  example  shows  a typical  use  of  the  WinMessageBox  function  when  debugging  an  application. 
The  C run-time  function  sprintf  is  used  to  format  the  body  of  the  message.  In  this  case,  it  converts 
the  coordinates  of  the  mouse  pointer  (retrieved  with  the  WinQueryPointerPos  function)  into  a string. 
The  string  is  then  displayed  by  calling  WinMessageBox. 


Idefine  INCL_WINDIALOGS  /*  Window  Dialog  Mgr  Functions  */ 
Idefine  INCL_WINPOINTERS  /*  Window  Pointer  Functions  */ 
linclude  <os2.h> 


CHAR  szMsg[10O];  /*  message 

POINTL  ptl ; /*  message  data 

HWND  hwndClient;  /*  client  window  handle 

WinQueryPointerPos(HWND_DESKTOP,  &ptl) ; 
sprintf(szMsg,  "x  = Id  y = Id",  ptl.x,  ptl.y); 

Wi nMessageBox ( HWND_DESKTOP , 

hwndClient,  /*  client-window  handle  */ 

szMsg,  /*  body  of  the  message  */ 

"Debugging  information",  /*  title  of  the  message  */ 

0,  /*  message  box  id  */ 

MB_N0IC0N  | MB_0K) ; /*  icon  and  button  flags  */ 


*/ 

*/ 

*/ 
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WinMultWindowFromIDs  - 

Get  Multiple  Windows  From  Identities 


#define  INCL_WINWINDOWMGR  /*  Or  use  INCL_WIN  or  INCL_PM  */ 


LONG  WinMultWindowFromIDs  (HWND  hwndParent,  PHWND  ahwnd,  ULONG  ulFIrst, 

ULONG  uiLast) 


This  function  finds  the  handles  of  child  windows  that  belong  to  a specified  window  and  have  window 
identities  within  a specified  range. 


Parameters 

hwndParent  (HWND)  - input 
Parent-window  handle. 

ahwnd  (PHWND)  - output 
Window  handles. 

This  array  must  contain  (uiLast  — ulFirst  + 1)  elements.  The  handle  of  a window,  whose  identity 
is  WID  (in  the  range  ulFirst  to  uiLast),  has  a zero-based  index  in  the  array  of  (WID  — ulFirst).  If 
there  is  no  window  for  a window  identity  within  the  range,  the  corresponding  element  in  the 
array  is  NULLHANDLE. 

ulFirst  (ULONG)  - input 

First  window  identity  value  in  the  range  (inclusive). 
uiLast  (ULONG)  - input 

Last  window  identity  value  in  the  range  (inclusive). 


Returns 

Number  of  window  handles  returned: 

0 No  window  handles  returned 
Other  Number  of  window  handles  returned. 

Possible  returns  from  WinGetLastError 

PMERR  INVALID  HWND  An  invalid  window  handle  was  specified. 

Remarks 

This  function  can  be  used  to  enumerate  all  the  items  in  a dialog  group,  or  to  enumerate  all  the  frame 
controls  of  a standard  window.  This  function  is  faster  than  individual  calls  to  the  WinWindowFromID 
function. 

Related  Functions 

• WinBeginEnumWindows 

• WinEndEnumWindows 

• WinEnumDIgltem 

• WinGetNextWindow 

• WinlsChild 

• WinQueryWindow 

• WinSetOwner 

• WinSetParent 
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WinMultWindowFromIDs  - 
Get  Multiple  Windows  From  Identities 


Example  Code 

This  example  finds  the  handles  of  all  frame  controls  of  a specified  window  via  the 
WinMultWindowFromIDs  call.  The  handles  are  returned  in  an  array  of  window  handles,  and  after  the 
call  completes,  the  handle  for  the  minmax  control  window  is  assigned  to  a variable  if  a handle  for  it 
was  found  (i.e.  handle  not  equal  to  NULLHANDLE). 


Idefine  INCL_WINWINDOWMGR  /*  Window  Manager  Functions  */ 
fdefine  INCL_WINFRAMEMGR  /*  Window  Frame  Functions  */ 
linclude  <os2.h> 

HWND  hwndParent;  /*  parent  window  */ 
HWND  ahwnd[FID_CLIENT-FID_SYSMENU];  /*  window  handle  array  */ 
HWND  hwndMinMax;  /*  minmax  control  window  handle  */ 
LONG  1 Handles;  /*  number  of  handles  returned  */ 


/*  get  all  control  handles  between  and  including  system  menu  and 
client  windows  */ 

lHandles  = WinMultWindowFromIDs (hwndParent,  ahwnd,  FID_SYSMENU, 

FID_CLIENT) ; 

/*  if  any  handles  returned  and  the  handle  for  the  minmax  control  is 
not  null,  assign  a variable  to  the  minmax  handle  */ 
if  (lHandles  > 0 &&  ahwnd [FID_MINMAX  - 
FID_SYSMENU]  !=  NULLHANDLE) 
hwndMinMax  = ahwnd [FID_MINMAX  - FID_SYSMENU] ; 
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WinNextChar  - 
Move  to  Next  Character 


#define  INCL_WINCOUNTRY  /*  Or  use  INCL_WIN  or  INCL_PM  7 


PSZ  WinNextChar  (HAB  hab,  ULONG  ulCodepage,  ULONG  ulCountry,  PSZ  pszCurrentChar) 


This  function  moves  to  the  next  character  in  a string. 

Parameters 

hab  (HAB)  - input 

Anchor-block  handle. 

ulCodepage  (ULONG)  - input 
Code  page. 

ulCountry  (ULONG)  - input 
Country  code. 

pszCurrentChar  (PSZ)  - input 

Current  character  in  a null-terminated  string. 


Returns 

Next  character  in  the  null-terminated  string: 

NULL  End  of  string  reached 
Other  Next  character. 

Possible  returns  from  WinGetLastError 

PMERRJNVALID  STRING  PARM  The  specified  string  parameter  is  invalid. 

Remarks 

This  function  handles  DBCS  strings. 


Related  Functions 

• WinCompareStrings 

• WinLoadString 

• WinPrevChar 

• WinSubstituteStrings 

• WinUpper 

• WinUpperChar 
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WinNextChar  - 
Move  to  Next  Character 


Example  Code 

This  example  uses  WinNextChar  to  traverse  a string  until  a specified  character  is  found,  while 
maintaining  an  index  to  point  to  the  character's  position. 


fdefine  INCL_WINCOUNTRY  /*  Window  Country  Functions  */ 
linclude  <os2.h> 

HAB  hab;  /*  anchor-block  handle  */ 
ULONG  idCodepage=437;  /*  Code  page  identity  of  both  strings  */ 
ULONG  idCountryCode=l;/*  Country  code  */ 
char  pszStringl[10] ; /*  first  string  */ 
char  *pszNextChar;  /*  next  character  */ 
char  *pszCurrentChar;  /*  current  character  */ 
ULONG  ul Index;  /*  array  index  */ 


/*  set  string  */ 
strcpy(pszStringl, "Compare") ; 

pszCurrentChar  = pszStringl; 
do 

{ 

pszNextChar  = WinNextChar(hab,  idCodepage,  idCountryCode, 

(psz)pszCurrentChar) ; 

if  (pszCurrentChar [0]  ==  1 p 1 ) 
break; 

ullndex++; 

} 

while  (pszNextChar  !=  NULL); 
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WinOffsetRect  - 
Offset  Rectangle 


#define  INCL_WINRECTANGLES  /*  Or  use  INCL_WIN  or  INCL_PM  */ 


BOOL  WinOffsetRect  (HAB  hab,  PRECTL  prclrect,  LONG  lex,  LONG  Icy) 


This  function  offsets  a rectangle. 


Parameters 

hab  (HAB)  - input 

Anchor-block  handle. 

prclrect  (PRECTL)  - input/output 
Rectangle  to  be  offset. 

Note:  The  value  of  each  field  in  this  structure  must  be  in  the  range  —32  768  through  32  767.  The 
data  type  WRECT  may  also  be  used,  if  supported  by  the  language. 

lex  (LONG)  — input 
x-value  of  offset. 

Icy  (LONG)  - input 
y-value  of  offset. 


Returns 

Success  indicator: 

TRUE  Successful  completion 
FALSE  Error  occurred. 

Remarks 

This  function  offsets  the  coordinates  of  prclrect  by  adding  the  value  of  the  lex  parameter  to  both  the 
left  and  right  coordinates,  and  the  value  of  the  Icy  to  both  the  top  and  bottom  coordinates. 


Related  Functions 

• WinCopyRect 

• WinEqualRect 

• WinFillRect 

• WinlnflateRect 

• WinlntersectRect 

• WinlsRectEmpty 

• WinPtlnRect 

• WinSetRect 

• WinSetRectEmpty 

• WinSubtractRect 

• WinUnionRect 
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WinOffsetRect  - 
Offset  Rectangle 


Example  Code 

This  example  moves  a rectangle  in  response  to  the  movement  of  the  mouse  (WM  MOUSEMOVE); 
the  rectangle  is  moved  (offset)  based  on  the  distance  moved  by  the  mouse  since  its  previous 
position. 

Idefine  I NCL_WINRECT ANGLES  /*  Window  Rectangle  Functions  */ 

finclude  <os2.h> 


int  main(void) 

{ 

BOOL  fSuccess;  /*  success  indicator  */ 

HAB  hab;  /*  anchor-block  handle  */ 

RECTL  prcl Recti  = {0,0,100,100};  /*  rectangle  */ 

LONG  lex;  /*  Horizontal  expansion  */ 

LONG  Icy;  /*  Vertical  expansion  */ 

POINTL  ptlPrev;  /*  previous  mouse  position  */ 

POINTL  ptlCurr;  /*  current  mouse  position  */ 

MPARAM  mpl;  /*  Parameter  1 (x,y)  point  value  */ 


case  WM_M0USEM0VE: 

ptlCurr. x = (LONG)  SHORTlFROMMP(mpl) ; 
ptlCurr. y = (LONG)  SH0RT2FR0MMP(mpl) ; 

/*  calculate  distance  from  previous  mouse  position  */ 
lex  = (LONG) (ptlPrev. x - ptlCurr. x); 

Icy  = (LONG) (ptlPrev. y - ptlCurr. y); 

fSuccess  = WinOffsetRect (hab,  SprclRectl,  lex,  Icy); 
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WinOpenClipbrd 
Open  Clipboard 


#define  INCL_WINCLIPBOARD  /*  Or  use  INCL.WIN  or  INCL_PM  7 


BOOL  WinOpenClipbrd  (HAB  hab) 


This  function  opens  the  clipboard. 

Parameters 

hab  (HAB)  - input 

Anchor-block  handle. 


Returns 

Success  indicator: 

TRUE  Clipboard  successfully  opened 
FALSE  Error  occurred. 

Remarks 

The  process  reading  the  clipboard  does  not  become  the  owner  of  the  object  in  it;  it  must  not  update 
or  free  the  object. 

This  function  prevents  other  threads  and  processes  from  examining  or  changing  the  clipboard 
contents. 

If  another  thread  or  process  already  has  the  clipboard  open,  this  function  does  not  return  until  the 
clipboard  is  closed. 

Messages  can  be  received  from  other  threads  and  processes  during  the  processing  of  this  function. 


Related  Functions 

• WinCloseClipbrd 

• WinEmptyClipbrd 

• WinEnumClipbrdFmts 

• WinQueryClipbrdData 

• WinQueryClipbrdFmtlnfo 

• WinQueryClipbrdOwner 

• WinQueryClipbrdViewer 

• WinSetClipbrdData 

• WinSetClipbrdOwner 

• WinSetClipbrdViewer 

Example  Code 

This  example  opens  the  clipboard  for  use  by  the  current  process. 

Idefine  INCL_WINCLIPBOARD  /*  Window  Clipboard  Functions  */ 

linclude  <os2.h> 

BOOL  fSuccess;  /*  success  indicator  */ 

HAB  hab;  /*  anchor-block  handle  */ 

fSuccess  = WinOpenCl ipbrd(hab) ; 
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WinOpenWindowDC  - 
Open  Window  Device  Context 


#define  INCL_WINWINDOWMGR  /*  Or  use  INCL_WIN  or  INCL_PM.  Also  in  COMMON  section  */ 


HDC  WinOpenWindowDC  (HWND  hwnd) 


This  function  opens  a device  context  for  a window. 

Parameters 

hwnd  (HWND)  - input 
Window  handle. 


Returns 

Device-context  handle. 

Possible  returns  from  WinGetLastError 

PMERR  INVALID  HWND  An  invalid  window  handle  was  specified. 

Remarks 

hdc  is  used  to  associate  a presentation  space  with  the  window. 

Note:  The  window  device  context  is  automatically  closed  when  its  associated  window  is  destroyed. 
It  must  not  be  closed  with  the  DevCIoseDC  call. 

The  visible  region  of  the  device  context  is  updated  automatically  as  windows  are  rearranged. 


Related  Functions 

• WinBeginPaint 

• WinEnableWindowllpdate 

• WinEndPaint 

• WinExcludellpdateRegion 

• WrnGetClipPS 

• WinGetPS 

• WinGetScreenPS 

• WinlnvalidateRect 

• WinlnvalidateRegion 

• WinlsWindowShowing 

• WinlsWindowVisible 

• WinLockVisRegions 

• WinQueryllpdateRect 

• WinQueryUpdateRegion 

• WinRealizePalette 

• WinReleasePS 

• WinShowWindow 

• WinllpdateWindow 

• WinValidateRect 

• WinValidateRegion 
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WinOpenWindowDC  - 
Open  Window  Device  Context 


Example  Code 

This  example  calls  WinOpenWindowDC  to  open  a device  context  for  a window,  the  handle  to  which 
is  then  used  to  associate  a presentation  space  with  the  window. 


fdefine  INCL_WINWINDOWMGR  /*  Window  Manager  Functions  */ 
fdefine  INCL_GPICONTROL  /*  Gpi  Control  Functions  */ 
finclude  <os2.h> 

HWNO  hwnd;  /*  window  handle  */ 
HPS  hps;  /*  presentation-space  handle  */ 
SIZEL  pagesize={OL,0L};  /*  Presentation  page  size  */ 
HAB  hab;  /*  Anchor-block  handle  */ 
HDC  hdc;  /*  device-context  handle  */ 

case  WMCREATE:  /*  Window  just  created  */ 


hdc  = WinOpenWindowDC(hwnd) ; 

hps  = GpiCreatePS(hab, 
hdc, 

&pagesize, 
PU_PELS  | 
GPIF_L0NG  | 
GPIA_ASSOC) ; 


/*  Open  window  device  context  */ 

/*  Create  GPI  PS  and  */ 

/*  associate  with  DC  */ 

/*  default  size  */ 

/*  pixel  units  */ 

/*  4-byte  coordinates  */ 

/*  associate  with  device  */ 
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WinPeekMsg  - 
Peek  Message 


#define  INCL_WINMESSAGEMGR  /*  Or  use  INCL_WIN  or  INCL_PM.  Also  in  COMMON  section  */ 


BOOL  WinPeekMsg  (HAB  hab,  PQMSG  pqmsgmsg,  HWND  hwndFllter,  ULONG  uiFirst, 
ULONG  uiLast,  ULONG  fiOptlons) 


This  function  inspects  the  thread’s  message  queue  and  returns  to  the  application  with  or  without  a 
message. 

Parameters 

hab  (HAB)  - input 

Anchor-block  handle. 

pqmsgmsg  (PQMSG)  - output 
Message  structure. 

hwndFllter  (HWNO)  - input 
Window  filter. 

uiFirst  (ULONG)  - input 
First  message  identity. 

uiLast  (ULONG)  - input 
Last  message  identity. 

fiOptlons  (ULONG)  - input 
Options. 

If  neither  of  the  following  flags  is  specified,  the  message  is  not  removed.  If  both  of  the  following 
flags  are  specified,  the  message  is  removed: 

PM_REMOVE  Remove  message  from  queue 

PM_NOREMOVE  Do  not  remove  message  from  queue. 

Returns 

Message-available  indicator: 

TRUE  Message  available 
FALSE  No  message  available. 

Possible  returns  from  WinGetLastError 

PMERRINVALID  HWND  An  invalid  window  handle  was  specified. 

PMERR_INVALID_FLAG  An  invalid  bit  was  set  for  a parameter.  Use  constants 

defined  by  PM  for  options,  and  do  not  set  any  reserved 
bits. 


Remarks 

This  function  is  identical  to  the  WinGetMsg  function,  except  that  it  does  not  wait  for  the  arrival  of  a 
message.  The  message  can  be  left  on  the  queue,  by  using  flOptions. 

For  details  of  hwndFilter,  uiFirst,  and  uiLast,  see  the  WinGetMsg  function. 

The  window  handle  within  pqmsgmsg  is  null  if  the  message  is  posted  to  the  queue  with  a hwnd  that 
is  null. 
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Related  Functions 

• WinCancelShutdown 

• WinBroadcastMsg 

• WinCreateMsgQueue 

• WinDestroyMsgQueue 

• WinDispatchMsg 

• WinGetDIgMsg 

• WinGetMsg 

• WinlnSendMsg 

• WinPostMsg 

• WinPostQueueMsg 

• WinQueryMsgPos 

• WinQueryMsgTime 

• WinQueryQueuelnfo 

• WinQueryQueueStatus 

• WinRegisterllserDatatype 

• WinRegisterllserMsg 

• WinSendDIgltemMsg 

• WinSendMsg 

• WinSetClassMsglnterest 

• WinSetMsglnterest 

• WinSetMsgMode 

• WinSetSynchroMode 

• WinWaitMsg 

Example  Code 

This  example  uses  WinPeekMsg  to  count  the  total  number  of  pending  messages  for  the  window 
corresponding  to  hwndFilter. 


Idefine  I NCL_WI NMESSAGEMGR  /*  Window  Message  Functions  */ 
Idefine  INCL_WINWINDOWMGR  /*  Window  Manager  Functions  */ 
linclude  <os2.h> 

HAB  hab;  /*  anchor-block  handle  */ 
QMSG  qmsg;  /*  message  */ 
HWND  hwndFilter;  /*  message  queue  filter  */ 
ULONG  flOptions;  /*  peek  options  */ 
ULONG  ulMsgCount-0;  /*  message  count  */ 


/*  don't  remove  messages  */ 
flOptions  = PM_N0REM0VE; 

/*  count  number  of  messages  for  filter  window  */ 
while  (WinPeekMsg  (hab,  Sqmsg,  hwndFilter,  0,  0,  flOptions)) 
ulMsgCount++; 
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#define  INCL_WINWINDOWMGR  /*  Or  use  INCL_WIN  or  INCL_PM  */ 


BOOL  WinPopupMenu  (HWND  hwndParent,  HWND  hwndOwner,  HWND  hwndMenu,  LONG  lx, 
LONG  ly,  ULONG  Idltem,  USHORT  (sOptlons) 


This  function  causes  a pop-up  menu  to  be  presented. 


Parameters 

hwndParent  (HWND)  - input 
Parent-window  handle. 

hwndOwner  (HWND)  - input 
Owner-window  handle. 

The  owner  window  receives  all  the  notification  messages  generated  by  the  pop-up  menu. 

hwndMenu  (HWND)  - input 

Pop-up  menu-window  handle. 

The  pop-up  menu  must  have  been  created,  by  use  of  either  the  WinCreateMenu  or  WinLoadMenu 
functions. 

lx  (LONG)  - input 

x-coordinate  of  the  pop-up  menu  position. 

The  value  is  in  window  coordinates  relative  to  the  origin  of  the  parent  window. 

The  x-coordinate  of  the  origin  of  the  pop-up  menu  can  be  affected,  if  either  of  the 
PU_POSITIONONITEM  or  PU_HCONSTRAIN  values  of  the  fsOptions  parameter  is  also  set. 

ly(LONG)  - input 

y-coordinate  of  the  pop-up  menu  position. 

The  value  is  in  window  coordinates  relative  to  the  origin  of  the  parent  window. 

The  y-coordinate  of  the  origin  of  the  pop-up  menu  can  be  affected,  if  either  of  the 
PU_POSITIONONITEM  or  PU_VCONSTRAIN  values  of  the  fsOptions  parameter  is  also  set. 

Idltem  (ULONG)  - input 
Item  identity. 

This  is  used  if  either  the  PU_POSITIONONITEM  or  PU_SELECTITEM  of  the  fsOptions  parameter  is 
also  set. 

fsOptions  (USHORT)  - input 
Options. 

Position 

Pop-up  menu  position. 

PU_POSITIONONITEM  Position  the  pop-up  menu  so  that  the  item  identified  by  the  idltem 
parameter  of  the  top-level  menu  specified  by  the  hwndMenu 
parameter  lies  directly  under  the  pointer. 

The  position  of  the  pop-up  menu  can  be  affected,  if  either  the 
PU_HCONSTRAIN  or  or  PU_VCONSTRAIN  values  of  the  fsOptions 
parameter  is  also  set. 

This  value  also  causes  the  pop-up  menu  item  identified  by  the 
idltem  to  be  selected. 
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Restrain 

Pop-up  menu  position  constraints. 

These  options  allow  the  application  to  ensure  that  the  pop-up  menu  is  visible  on  the 
desktop. 

PU_HCONSTRAIN  Constrain  the  pop-up  menu  so  that  its  width  is  wholly  visible  on  the 
desktop. 

if  necessary  the  position  of  the  pop-up  menu  will  be  adjusted  so  that  its 
left  edge  is  coincident  with  the  left  edge  of  the  desktop  or  that  its  right 
edge  is  coincident  with  the  right  edge  of  the  desktop. 

PU_VCONSTRAIN  Constrain  the  pop-up  menu  so  that  its  height  is  wholly  visible  on  the 
desktop. 

If  necessary  the  position  of  the  pop-up  menu  will  be  adjusted  so  that  its 
top  edge  is  coincident  with  the  top  edge  of  the  desktop  or  that  its  bottom 
edge  is  coincident  with  the  bottom  edge  of  the  desktop. 

InitlaiState 

Initial  input  state  of  the  pop-up  menu. 

This  allows  the  user  interaction  which  caused  the  application  to  summon  the  pop-up  menu 
to  be  carried  through  as  the  initial  user  interaction  with  the  pop-up  menu. 

For  example,  this  permits  the  application  to  support  the  user  interface  in  which  mouse 
button  1 can  be  depressed  to  cause  the  pop-up  menu  to  be  presented  and  held  down  while 
moving  the  mouse  over  the  menu  in  order  to  select  another  menu  item  and  then  released  to 
dismiss  the  menu. 

Only  one  of  the  following  values  can  be  selected: 

PU_MOUSEBUTTON1  DOWN  The  pop-up  menu  is  initialized  with  mouse  button  1 

depressed. 

PU_MOUSEBUTTON2DOWN  The  pop-up  menu  is  initialized  with  mouse  button  2 

depressed. 

PU_MOUSEBUTTON3DOWN  The  pop-up  menu  is  initialized  with  mouse  button  3 

depressed. 

PU_NONE  The  pop-up  menu  is  to  be  presented  uninfluenced  by  the  user 

interaction  which  caused  it  to  be  summoned. 

This  is  the  default  value. 

Select 

Item  selection. 

PU_SELECTITEM  The  item  identified  by  idltem  is  to  be  selected.  This  is  only  valid  if 
PU_NONE  is  set  in  the  InitialState  parameter. 

If  the  identified  item  is  in  a submenu  of  the  pop-up  menu,  then  all  the 
previous  submenus  in  the  menu  hierarchy  are  presented  with  the 
correct  path  to  the  identified  item. 

Usage 

Input  device  usage. 

The  window  procedure  controlling  the  pop-up  menu  must  be  informed  of  which  input  devices 
are  available  for  interaction  with  the  pop-up  menu. 

These  options  are  independent  to  those  of  the  InitialState  parameter.  Therefore,  if  an 
application  indicates  in  the  InitialState  parameter  that  the  pop-up  menu  is  to  be  initialized 
with  a particular  user  interaction,  then  the  mechanism  which  permits  that  user  interaction 
would  usually  be  specified  in  this  parameter.  In  this  way  the  user’s  expectation,  that  once  a 
device  has  been  employed  for  the  manipulation  of  the  pop-up  menu  then  that  device  can 
continue  to  be  used  for  that  purpose,  is  fulfilled. 
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It  is  valid  to  specify  a user  interaction  as  an  initialization  of  the  pop-up  menu  by  an  input 
mechanism  which  is  not  identified  as  available  for  interaction  with  the  pop-up  menu.  This 
implies  that  the  user  cannot  necessarily  complete  the  interaction  with  the  pop-up  menu  with 
that  input  mechanism. 

For  example,  if  a pop-up  menu  is  initialized  with  a mouse  button  depressed  but  that  mouse 
button  is  not  identified  as  available  for  manipulating  the  pop-up  menu,  then  that  mouse 
button  can  manipulate  the  pop-up  menu  until  it  is  released.  Assuming  that  the  pop-up  menu 
is  not  dismissed  when  that  mouse  button  is  released,  then  the  mouse  button  cannot  be  used 
for  further  interaction  with  the  pop-up  menu,  since  it  is  not  identified  as  available  for  that 
use. 


The  following  list  shows  the  input  device  valid  for  interaction  with  the  pop-up  menu  with 
each  option: 


PUKEYBOARD 
PUMOUSEBUTTON1 
PU_M  OUSEBUTTON2 
PUMOUSEBUTTON3 


The  keyboard. 
Mouse  button  1. 
Mouse  button  2. 
Mouse  button  3. 


Returns 

Pop-up  menu  invoked  indicator: 

This  function  returns  as  soon  as  the  pop-up  menu  has  been  invoked,  which  might  be  before  the 
user  has  completed  interacting  with  the  pop-up  menu. 

TRUE  Pop-up  menu  successfully  invoked. 

FALSE  Pop-up  menu  not  successfully  invoked. 

Remarks 

A pop-up  menu  is  the  unanchored  equivalent  of  a pull-down  menu,  that  is  it  can  be  positioned 
anywhere  rather  than  being  associated  with  an  action  bar.  Typically,  pop-up  menus  are  related  to 
specific  objects,  such  as  an  icon,  or  with  a particular  area  of  the  application’s  presentation  space. 

Once  invoked,  a pop-up  menu  behaves  in  exactly  the  same  way  as  a pull-down  menu. 


Related  Functions 

• WinCreateMenu 

• WinLoadMenu 
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Example  Code 

This  example  presents  a pop-up  menu  (loaded  from  RES. DLL  by  WinLoadMenu)  with  the  following 
characteristics:  located  at  (0,50);  initialized  with  mouse  button  1 depressed;  allowing  keyboard  and 
mouse  button  1 interaction. 


Idefine  INCL_WINWIND0WMGR  /*  Window  Manager  Functions  */ 
Idefine  INCL_WINMENUS  /*  Window  Menu  Functions  */ 
linclude  <os2.h> 


HWND  hwndMenu; 
HWND  hwndOwner; 
HMODULE  hmodDLL; 
ULONG  idMenuid; 
BOOL  f Success; 

HWND  hwndParent; 
ULONG  fl  Options; 


/*  menu  window 
/*  owner  window 
/*  resource  handle 
/*  resource  menu  id 
/*  success  indicator 
/*  parent  window 
/*  pop-up  menu  options 


*/ 

*/ 

*/ 

*/ 

*/ 

*/ 

*/ 


i f (DosQueryModul eHandl e ( " RES . DLL" , ShmodDLL) ) 

hwndMenu  = WinLoadMenu(hwndOwner,  hmodDLL,  idMenuid); 


fl Options  = PU_M0USEBUTT0N1D0WN  | PU_KEYBOARD  | PU_MOUSEBUTTON1; 
fSuccess  = WinPopupMenu(hwndParent,  hwndOwner,  hwndMenu,  0,  50, 
0,  fl Options); 
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#define  INCL_WINMESSAGEMGR  /*  Or  use  INCL_WIN  or  INCL_PM.  Also  in  COMMON  section  */ 


BOOL  WinPostMsg  (HWND  hwnd,  ULONG  ulMsgld,  MPARAM  mpParaml, 
M PAR  AM  mpParam2) 


This  function  posts  a message  to  the  message  queue  associated  with  the  window  defined  by  hwnd. 


Parameters 

hwnd  (HWND)  - input 
Window  handle: 

NULL  The  message  is  posted  into  the  queue  associated  with  the  current  thread.  When  the 
message  is  received  by  using  the  WinGetMsg  or  WinPeekMsg  functions,  the  hwnd 
parameter  of  the  QMSG  structure  is  NULL. 

Other  Window  handle. 

ulMsgld  (ULONG)  - input 
Message  identity. 

mpParaml  (MPARAM)  - input 
Parameter  1 . 

mpParam2  (MPARAM)  - input 
Parameter  2. 


Returns 

Message-posted  indicator: 

TRUE  Message  successfully  posted 

FALSE  Message  could  not  be  posted;  for  example,  because  the  message  queue  was  full. 
Possible  returns  from  WinGetLastError 

PMERRJNVALID  HWND  An  invalid  window  handle  was  specified. 

Remarks 

The  message  contains  hwnd,  ulMsgid,  mpParaml,  mpParam2,  and  the  time  and  pointer  position 
when  this  function  is  called. 

WinPostMsg  returns  immediately,  while  WinSendMsg  waits  for  the  receiver  to  return. 

A thread  which  does  not  have  a message  queue  can  still  call  WinPostMsg  but  cannot  call 
WinSendMsg. 
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Related  Functions 

• WinBroadcastMsg 

• WinCreateMsgQueue 

• WinDestroyMsgQueue 

• WinDispatchMsg 

• WinGetDIgMsg 

• WinGetMsg 

• WinlnSendMsg 

• WinPeekMsg 

• WinPostQueueMsg 

• WinQueryMsgPos 

• WinQueryMsgTime 

• WinQueryQueuelnfo 

• WinQueryQueueStatus 

• WinRegisterUserDatatype 

• WinRegisterUserMsg 

• WinSendDIgltemMsg 

• WinSendMsg 

• WinSetClassMsglnterest 

• WinSetMsglnterest 

• WinSetMsgMode 

• WinSetSynchroMode 

• WinWaitMsg 

Example  Code 

This  example  posts  a Set  menu  item  checked  attribute  message  ( M M_SETITEM ATTR)  to  the 
message  queue  associated  with  the  window  handle  in  response  to  a menu  select  message 
(WM_MENUSELECT). 


Idefine  I NCL_WI NMESSAGEMGR  /*  Window  Message  Functions  */ 
Idefine  INCL_WINMENUS  /*  Window  Menu  Functions  */ 
linclude  <os2.h> 

BOOL  fResult;  /*  message-posted  indicator  */ 
ULONG  ulMsgid;  /*  message  id  */ 
MPARAM  mpl;  /*  Parameter  1 (recti  structure)  */ 
MPARAM  mp2;  /*  Parameter  2 (frame  boolean)  */ 
USHORT  usltemld;  /*  menu  item  id  */ 
HWND  hwndMenu;  /*  menu  handle  */ 


case  WM_MENUSELECT : 

usltemld  = SHORTlFROMMP(mpl) ; 
hwndMenu  = HWNDFR0MMP(mp2) ; 

/*  initialize  message  id,  parameters  */ 
ulMsgid  = MMJETITEMATTR; 
mpl  = MPFR0M2SH0RT(usItemId,  TRUE); 
mp2  = MPFR0M2SH0RT(MIA_CHECKED,  TRUE); 

fResult  = WinPostMsg (hwndMenu,  ulMsgid,  mpl,  mp2); 
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#define  INCL_WINMESSAGEMGR  /*  Or  use  INCL_WIN  or  INCL_PM  */ 


BOOL  WinPostQueueMsg  (HMQ  hmq,  ULONG  ulMsgld,  MPARAM  mpParaml, 

MPARAM  mpParam2) 


This  function  posts  a message  to  a message  queue. 


Parameters 

hmq  (HMQ)  - input 

Message-queue  handle. 

ulMsgld  (ULONG)  - input 
Message  identifier. 

mpParaml  (MPARAM)  - input 
Parameter  1. 

mpParam2  (MPARAM)  - input 
Parameter  2. 


Returns 

Success  indicator: 

TRUE  Successful  completion 

FALSE  Error  occurred,  or  the  queue  was  full. 

Possible  returns  from  WinGetLastError 

PMERR  INVALID  HMQ  An  invalid  message-queue  handle  was  specified. 

Remarks 

This  function  can  be  used  to  post  messages  to  any  queue  in  the  system. 

It  constructs  a QMSG  structure  by  setting  its  hwnd  parameter  to  NULL,  setting  its  msg,  mpl,  and  mp2 
parameters  from  the  corresponding  parameters  of  this  function,  and  by  deriving  its  time  and  ptl 
parameters  from  the  system  time  and  pointer  position  when  this  function  was  called.  The  QMSG 
structure  is  then  placed  on  the  specified  queue. 
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Related  Functions 

• WinBroadcastMsg 

• WinCreateMsgQueue 

• WinDestroyMsgQueue 

• WinDispatchMsg 

• WinGetDIgMsg 

• WinGetMsg 

• WinlnSendMsg 

• WinPeekMsg 

• WinPostMsg 

• WinQueryMsgPos 

• WinQueryMsgTime 

• WinQueryQueuelnfo 

• WinQueryQueueStatus 

• WinRegisterllserDatatype 

• WinRegisterUserMsg 

• WinSendDIgltemMsg 

• WinSendMsg 

• WinSetClassMsglnterest 

• WinSetMsglnterest 

• WinSetMsgMode 

• WinSetSynchroMode 

• WinWaitMsg 


Example  Code 

This  example  posts  a Set  menu  item  checked  attribute  message  (MM_SETITEMATTR)  to  the 
specified  message  queue  in  response  to  a menu  select  message  (WM_MENUSELECT). 


Idefine  INCL_WINMESSAGEMGR  /*  Window  Message  Functions  */ 
Idefine  INCL_WINMENUS  /*  Window  Menu  Functions  */ 
#include  <os2.h> 

BOOL  fResult;  /*  message-posted  indicator  */ 
ULONG  ulMsgid;  /*  message  id  */ 
HMQ  hmq;  /*  message  queue  handle  */ 
MPARAM  mpl;  /*  Parameter  1 (recti  structure)  */ 
MPARAM  mp2;  /*  Parameter  2 (frame  boolean)  */ 
USHORT  usltemld;  /*  menu  item  id  */ 


case  WMJOUSELECT: 

usltemld  = SHORTlFROMMP(mpl) ; 

/*  initialize  message  id,  parameters  */ 
ulMsgid  = MM_SETITEMATTR; 
mpl  = MPFR0M2SH0RT(usItemId,  TRUE); 
mp2  = MPFR0M2SH0RT(MIA_CHECKED,  TRUE); 

fResult  = WinPostQueueMsg (hmq,  ulMsgid,  mpl,  mp2); 
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#define  INCL_WINCOUNTRY  /*  Or  use  INCL_WIN  or  INCL_PM  */ 


PSZ  WinPrevChar  (HAB  hab,  ULONG  uiCodepage,  ULONG  uiCountry,  PSZ  pszStart, 
PSZ  pszCurrentChar) 


This  function  moves  to  the  previous  character  in  a string. 


Parameters 

hab  (HAB)  - input 

Anchor-block  handle. 

uiCodepage  (ULONG)  - input 
Code  page. 

uiCountry  (ULONG)  - input 
Country  code. 

pszStart  (PSZ)  - input 

Character  string  that  contains  pszCurrentChar. 

pszCurrentChar  (PSZ)  - input 
Current  character. 


Returns 

Previous  character. 

The  previous  character,  or  the  first  character  if  pszCurrentChar  is  the  first  character  of  pszStart. 
Possible  returns  from  WinGetLastError 

PMERR  INVALID  STRING  PARM  The  specified  string  parameter  is  invalid. 

Remarks 

This  function  handles  DBCS  strings. 


Related  Functions 

• WinCompareStrings 

• WinLoadString 

• WinNextChar 

• WinSubstituteStrings 

• WinUpper 

• WinUpperChar 
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Example  Code 

This  example  uses  WinPrevChar  to  return  a pointer  to  the  previous  character  in  a string. 

Idefine  INCL_DOSNLS 
Idefine  INCL_WINCOUNTRY 
linclude  <0S2.H> 
linclude  <stdio.h> 

Idefine  CURRENT_COUNTRY  0 

main() 

{ 

HAB  hab;  /*  anchor-block  handle.  */ 

char  string []  = "ABCDEFGHIJ"; 
char  *ptoE  = &string[4]; 
char  *ptoD; 

ULONG  CodePage;  /*  List  (returned)  */ 

ULONG  DataLength;  /*  Length  of  list  (returned)  */ 

COUNTRYCODE  Country; 

COUNTRYINFO  CtryBuffer; 

Country. country  = CURRENT_COUNTRY ; 

DosQueryCp((UL0NG)2, 

SCodePage,  /*  get  code  page  identifier  of  calling  */ 

/*  process.  */ 

&DataLength) ; 

/*  first  WORD  contains  the  codepage.  */ 

Country. codepage  = (ULONG)HIUSHORT(CodePage) ; 

/*  get  corresponding  country  code  */ 

DosQueryCtryInfo(sizeof(CtryBuffer) , /*  Length  of  data  area  */ 

/*  provided  */ 

&Country,  /*  Input  data  structure  */ 

&CtryBuffer,  /*  Data  area  to  be  filled  */ 

/*  by  function  */ 

SDataLength) ; /*  Length  of  data  */ 

/*  should  return  a pointer  to  character  "D"  in  the  string  */ 

ptoD  = WinPrevChar(hab, 

(ULONG) CodePage, 

(ULONG) CtryBuffer. country , 

(PSZ)string, 

ptoE);  /*  pointer  to  character  "E"  in  the  */ 

/*  string.  */ 

printf  (ptoE) ; 

} 
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#define  INCL_WINDIALOGS  /*  Or  use  INCL_WIN  or  INCL_PM  7 


ULONG  WinProcessDIg  (HWND  hwndDig) 


This  function  dispatches  messages  while  a modal  dialog  window  is  displayed. 

Parameters 

hwndDig  (HWND)  - input 
Dialog-window  handle. 


Returns 

Reply  value. 

Value  established  by  the  WinDismissDIg  function. 

Possible  returns  from  WinGetLastError 

PMERR  INVALID  HWND  An  invalid  window  handle  was  specified. 

Remarks 

If  the  dialog  has  an  owner  window,  that  window  is  disabled.  This  means  that  all  user  input  to  the 
owner,  and  its  descendants,  is  prevented. 

This  function  then  dispatches  messages  from  the  queue  to  the  appropriate  window  or  dialog 
procedure  until  the  dialog  is  dismissed  by  the  WinDismissDIg  function.  This  is  usually  done  by  the 
dialog  procedure  on  receipt  of  an  appropriate  message,  but  also  occurs  if  the  dialog  procedure 
passes  a WM_COMMAND  message  to  WinDefDIgProc  or  if  a WM_QUIT  message  is  encountered 
before  the  dialog  window  is  dismissed.  In  this  latter  case,  WinProcessDIg  itself  issues  a 
WinDismissDIg  function,  and  posts  the  WM_QUIT  message  back  to  the  queue  so  that  the  application 
main  loop  terminates  in  the  normal  way. 

This  function  shows  the  window,  if  it  is  hidden,  when  the  queue  is  empty.  It  is  therefore  possible  for 
the  experienced  user  to  type  ahead  and  cause  the  dialog  to  be  dismissed  before  it  becomes  visible. 

The  WinDismissDIg  function  hides  the  dialog  window  without  destroying  it,  and  also  re-enables  any 
window  that  was  disabled  by  this  function. 

This  function  does  not  return  until  a WinDismissDIg  call  is  issued  in  one  of  the  ways  listed  above. 

This  is  true  even  if  the  application  main  window  has  not  been  disabled,  for  example  because  the 
dialog  window  has  no  owner.  In  this  case,  the  dialog  will  appear  to  the  user  to  be  modeless;  the  user 
will  continue  to  be  able  to  interact  with  the  application,  and  possibly  create  multiple  instances  of  the 
dialog.  In  such  circumstances  the  operating  system  calls  the  application  main  window  procedure 
recursively  before  WinProcessDIg  returns. 

It  is  not  possible  to  temporarily  disable  more  than  one  window  using  this  function;  a dialog  window 
can  have  at  most  one  owner.  If  an  application  has  more  than  one  main  window  which  should  be 
disabled  while  the  modal  dialog  is  displayed,  it  can  be  done  by  setting  appropriate  hooks  using  the 
WinSetHook  function. 

If  the  dialog  window  is  a descendant  of  its  owner,  this  function  disables  input  to  the  dialog  itself. 
However,  this  situation  can  only  occur  by  explicitly  changing  the  window  hierarchy.  Dialog  windows 
are  created  using  the  WinLoadDIg  or  WinCreateDIg  functions,  which  modify  the  owner  window 
specified  on  their  parameter  lists. 
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WinProcessDIg  - 
Process  Modal  Dialog 


Related  Functions 

• WinCreateDIg 

• WinDefDIgProc 

• WinDismissDIg 

• WinDIgBox 

• WinGetDIgMsg 

• WinLoadDIg 

Related  Messages 

• WM_COMMAND 

• WM_QUIT 

Example  Code 

This  function  is  used  to  process  messages  while  a dialog  is  active. 

Idefine  INCL_WIN 
Idefine  INCL_WINDIALOGS 
linclude  <0S2.H> 

Idefine  IDD_0PEN  WM_USER+200 
Idefine  I0M_0PEN  WMJJSER+201 

HWND  hwndDlg; 

HWND  hwndFrame; 

PFNWP  OpenDlg; 


/*  Inside  client  procedure.  */ 

switch (msg) 

{ 

case  WM_COMMAND: 

/*  The  user  has  chosen  a menu  item.  Process  the  selection  */ 
/*  accordingly.  */ 

switch  ( SH0RT1FR0MMP(  mpl  ) ) 

{ 

case  IDM_0PEN: 

if  (WinDlgBox(HWND_DESKTOP, 


hwndFrame,  /*  handle  of  the  owner  */ 

OpenDlg,  /*  dialog  procedure  address  */ 
(ULONG)0,  /*  location  of  dialog  resource  */ 

IDD_0PEN,  /*  resource  identifier  */ 

NULL))  { /*  application-specific  data  */ 


WinProcessDIg (hwndDlg) ; 

} 

break; 


} 

break; 
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WinPtlnRect  - 
Point  In  Rectangle 


#define  INCL_WINRECTANGLES  /*  Or  use  INCL_WIN  or  INCL_PM  */ 


BOOL  WinPtlnRect  (HAB  hab,  PRECTL  prclrect,  PPOINTL  pptlpolnt) 


This  function  queries  whether  a point  lies  within  a rectangle. 


Parameters 

hab  (HAB)  - input 

Anchor-block  handle. 

prclrect  (PRECTL)  - input 
Rectangle  to  be  queried. 

Note:  The  value  of  each  field  in  this  structure  must  be  in  the  range  —32  768  through  32  767.  The 
datatype  WRECT  may  also  be  used,  if  supported  by  the  language. 

pptlpolnt  (PPOINTL)  - input 
Point  to  be  queried. 


Returns 

Success  indicator: 

TRUE  pptlpoint  lies  within  prclrect 

FALSE  pptlpoint  does  not  lie  within  prclrect,  or  an  error  occurred. 

Related  Functions 

• WinCopyRect 

• WinEqualRect 

• WinFillRect 

• WinlnflateRect 

• WinlntersectRect 

• WinlsRectEmpty 

• WinOffsetRect 

• WinSetRect 

• WinSetRectEmpty 

• WinSubtractRect 

• WinllnionRect 
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WinPtlnRect  - 
Point  In  Rectangle 


Example  Code 

This  example  processes  a WM_BUTTON1UP  message,  converts  the  mouse  pointer  coordinates  into 
POINTL  structure,  and  calls  WinPtlnRect  to  determine  if  the  mouse  was  clicked  in  the  predefined 
global  rectangle. 

fdefine  INCL_WIN 
fdefine  INCL_WINRECT ANGLES 
finclude  <0S2.H> 

HAB  hab;  /*  anchor-block  handle  */ 

/*  • */ 

/*  . */ 

RECTL  rcl Global; 

POINTL  ptl ; 

HPS  hps; 

USHORT  msg; 

MPARAM  mpl; 

/*  inside  client  window  function.  */ 

switch (msg) 

{ 

case  WM_COMMAND: 

/*  The  user  has  chosen  a menu  item. 

/*  accordingly. 

switch  ( SH0RT1FR0MMP(  mpl  ) ) 

{ 


Process  the  selection  */ 
*/ 


case  WM  BUTT0N1UP: 
ptl .x  = (LONG)  SHORTlFROMMP(mpl); 
ptl .y  = (LONG)  SH0RT2FR0MMP(mpl) ; 

WinPtlnRect (hab,  /*  anchor-block  handle  */ 

&rcl Global,  /*  address  of  the  rectangle  */ 

&ptl ) ; /*  address  of  the  point  */ 


break; 

} 

break; 


} 
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WinQueryAccelTable  - 
Query  Accelerator  Table 


#define  INCL_WINACCELERATORS  /*  Or  use  INCL_WIN  or  INCL_PM  */ 


HACCEL  WinQueryAccelTable  (HAB  hab,  HWND  hwndFrame) 


This  function  queries  the  window  or  queue  accelerator  table. 


Parameters 

hab  (HAB)  - input 

Anchor-block  handle. 

hwndFrame  (HWND)  - input 
Frame-window  handle: 

NULLHANDLE  Return  queue  accelerator. 

Other  Return  the  window  accelerator  table,  by  sending  the  WM_QUERYACCELTABLE 

message  to  hwndFrame. 


Returns 

Accelerator-table  handle: 

NULLHANDLE  Error  occurred 

Other  Accelerator-table  handle. 

Possible  returns  from  WinGetLastError 

PMERR  INVALID  HWND  An  invalid  window  handle  was  specified. 

Related  Functions 

• WinCopyAccelTable 

• WinCreateAccelTable 

• WinDestroyAccelTable 

• WinLoadAccelTable 

• WinSetAccelTable 

• WinTranslateAccel 

Related  Messages 

• WM_QUERYACCELTABLE 
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WinQuery  Accel  Table  - 
Query  Accelerator  Table 


Example  Code 

This  example  shows  how  to  get  the  accelerator  table  for  the  frame  window. 

Idefine  INCL.WINWINDOWMGR 
Idefine  INCL_WINACCELERATORS 
finclude  <0S2.H> 

HACCEL  haccel ; 

HWND  hwndFrame,  hwndClient;  /*  window  handles.  */ 

HAB  hab ; /*  anchor  block.  */ 

hwndFrame  = WinQueryWindow(hwndClient, 

QW  PARENT);  /*  get  handle  of  parent,  */ 

/*  which  is  frame  window.  */ 


/*  Now  get  the  accel  table  for  the  frame  window  */ 
haccel  = WinQueryAccelTable(hab, 

hwndFrame) ; 
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WinQuery  Active  Window  - 
Query  Active  Window 


#define  INCL_WINWINDOWMGR  /*  Or  use  INCL_WIN  or  INCL_PM  */ 


HWND  WinQueryActlveWindow  (HWND  hwndParent) 


This  function  returns  the  active  window  for  HWND_DESKTOP,  or  other  parent  window. 

Parameters 

hwndParent  (HWND)  - input 

Parent-window  handle  for  which  the  active  window  is  required: 

HWND_DESKTOP  The  desktop-window  handle  that  causes  this  function  to  return  the  top-level 
frame  window. 

Other  Specified  parent-window  handle. 

Returns 

Active-window  handle: 

NULLHANDLE  No  window  is  active 
Other  Active-window  handle. 

Possible  returns  from  WinGetLastError 

PMERR  INVALID  HWND  An  invalid  window  handle  was  specified. 

Related  Functions 

• WinGetMinPosition 

• WinQueryWindowPos 

• WinSaveWindowPos 

• WinSetActiveWindow 

• WinSetMultWindowPos 

• WinSetWindowPos 

Example  Code 

This  example  shows  how  the  WinQueryActiveWindow  can  be  used  to  find  the  active  window. 

Idefine  INCL_WINWINDOWMGR 
linclude  <0S2.H> 

HWND  hwndActive; 

hwndActive  = WinQueryActiveWindow(HWND_DESKTOP) 
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WinQueryAnchorBlock 
Query  Anchor  Block 


#define  INCL_WINWINDOWMGR  /*  Or  use  INCL_WIN  or  INCL_PM.  Also  in  COMMON  section  7 


HAB  WinQueryAnchorBlock  (HWND  hwnd) 


This  function  returns  the  anchor  block  handle  of  the  caller. 

Parameters 

hwnd  (HWND)  - input 
Window  handle. 


Returns 

Anchor  block  handle. 

NULLHANDLE  Invalid  hwnd  parameter 
Other  Anchor  block  handle. 

Possible  returns  from  WinGetLastError 

PMERR  INVALID  HWND  An  invalid  window  handle  was  specified. 

Example  Code 

This  function  obtains  the  anchor  block  handle  of  the  caller. 

Idefine  INCL_WINWINDOWMGR 
linclude  <0S2.H> 

HAB  hab; 

HWND  hwnd; 

hab  = WinQueryAnchorBlock(hwnd) ; 
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WinQueryAtomLength  - 
Query  Atom  Length 


#define  INCLJVINATOM  /*  Or  use  INCL_WIN  or  INCL_PM  */ 


ULONG  WinQueryAtomLength  (HATOMTBL  hatomtbiAtomTbl,  ATOM  atom) 


This  function  queries  the  length  of  an  atom  represented  by  the  specified  atom. 


Parameters 

hatomtbiAtomTbl  (HATOMTBL)  - input 
Atom-table  handle. 

The  handle  returned  from  a previous  WinCreateAtomTable  or  WinQuerySystemAtomTable 
function. 

atom  (ATOM)  - input 

Atom  whose  associated  character-string  length  is  to  be  returned. 


Returns 

String  length: 

0 The  specified  atom  or  the  atom  table  is  invalid. 

Other  The  length  of  the  character  string  associated  with  the  atom  excluding  the  null 
terminating  byte.  Integer  atoms  always  return  a length  of  six. 

Possible  returns  from  WinGetLastError 

PMERRJNVALID  HATOMTBL  An  invalid  atom-table  handle  was  specified. 

PMERRJNVALID_ATOM  The  specified  atom  does  not  exist  in  the  atom  table. 

Remarks 

The  purpose  of  this  function  is  to  allow  an  application  to  determine  the  size  of  buffer  to  use  in  the 
WinQueryAtomName  call. 


Related  Functions 

• WinAddAtom 

• WinCreateAtomTable 

• WinDeleteAtom 

• WinDestroyAtomTable 

• WinFindAtom 

• WinQueryAtomName 

• WinQueryAtomllsage 

• WinQuerySystemAtomTable 
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WinQueryAtomLength  - 
Query  Atom  Length 

Example  Code 

This  function  queries  the  length  of  an  atom. 

Idefine  INCL_WINATOM 
finclude  <0S2.H> 

HATOMTBL  atomtbl ; 

ATOM  atom  = 25; 

Wi nQueryAtoml ength (atomtbl , /*  atom  handle 
atom) ; 
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WinQueryAtomName  - 
Query  Atom  Name 


#define  INCL_WINATOM  /*  Or  use  INCL_WIN  or  INCL_PM  */ 


ULONG  WinQueryAtomName  (HATOMTBL  hatomtblAtomTbl,  ATOM  atom,  PSZ  pszBuffer, 

ULONG  ulBufferMax) 


This  function  returns  an  atom  name  associated  with  an  atom. 

Parameters 

hatomtblAtomTbl  (HATOMTBL)  - input 
Atom-table  handle. 

The  handle  returned  from  a previous  WinCreateAtomTable  or  WinQuerySystemAtomTable 
function. 

atom  (ATOM)  - input 

Identifies  the  character  string  to  be  retrieved. 

pszBuffer  (PSZ)  - output 

Buffer  to  receive  the  character  string. 

ulBufferMax  (ULONG)  - input 
Buffer  size  in  bytes. 


Returns 

Length  of  retrieved  character  string: 

0 The  specified  atom  or  the  atom  table  is  invalid. 

Other  The  number  of  bytes  copied  to  the  buffer  excluding  the  terminating  zero. 

Possible  returns  from  WinGetLastError 

PMERRINVALIDHATOMTBL 
PMERRINVALIDATOM 
PMERRJNVALIDSTRINGPARM 

Remarks 

For  integer  atoms,  the  format  of  the  string  is  “#ddddd”  where  “ddddd”  are  decimal  digits  in  the 
system  code  page  (an  ASCII  code  page).  No  leading  zeros  are  generated,  and  the  length  can  be 
from  3 through  7 characters. 


An  invalid  atom-table  handle  was  specified. 

The  specified  atom  does  not  exist  in  the  atom  table. 
The  specified  string  parameter  is  invalid. 


Related  Functions 

• WinAddAtom 

• WinCreateAtomTable 

• WinDeleteAtom 

• WinDestroyAtomTable 

• WinFindAtom 

• WinQueryAtomLength 

• WinQueryAtomUsage 

• WinQuerySystemAtomTable 
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WinQueryAtomName  - 
Query  Atom  Name 

Example  Code 

This  function  obtains  the  name  of  an  atom  given  the  atom  id. 

fdefine  INCL_WINATOM 
linclude  <0S2.H> 

HATOMTBL  atomtbl ; 
char  atomname[256] ; 

ATOM  atom  = 25; 

WinQueryAtomName(atomtbl , 
atom, 
atomname, 

sizeof(atomname)) ; 
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WinQueryAtomUsage  - 
Query  Atom  Usage 


#define  INCL_WINATOM  /*  Or  use  INCL_WIN  or  INCL_PM  */ 


ULONG  WinQueryAtomUsage  (HATOMTBL  hatomtblAtomTbl,  ATOM  atom) 


This  function  returns  the  number  of  times  an  atom  has  been  used. 

Parameters 

hatomtblAtomTbl  (HATOMTBL)  - input 
Atom-table  handle. 

The  handle  returned  from  a previous  WinCreateAtomTable  or  WinQuerySystemAtomTable 
function. 

atom  (ATOM)  - input 

Atom  whose  use  count  is  to  be  returned. 


Returns 

Use  count  of  the  atom: 

65535  Integer  atom 

0 The  specified  atom  or  the  atom  table  is  invalid 

Other  Use  count. 

Possible  returns  from  WinGetLastError 

PMERRINVALIDHATOMTBL 
PMERRINVALIDATOM 

Related  Functions 

• WinAddAtom 

• WinCreateAtomTable 

• WinDeleteAtom 

• WinDestroyAtomTable 

• WinFindAtom 

• WinQueryAtomLength 

• WinQueryAtomName 

• WinQuerySystemAtomTable 

Example  Code 

This  function  returns  the  number  of  times  an  atom  has  been  used. 

fdefine  INCL_WINATOM 
#include  <0S2.H> 

HATOMTBL  atomtbl ; 

ATOM  atom  = 25; 

Wi nQueryAtoml ength( atomtbl , 
atom) ; 


An  invalid  atom-table  handle  was  specified. 

The  specified  atom  does  not  exist  in  the  atom  table. 
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WinQueryButtonCheckstate 
Query  Checkstate  of  Button 


#define  INCL_WINWINDOWMGR  /*  Or  use  INCL_WIN  or  INCL_PM  */ 


USHORT  WinQueryButtonCheckstate  (HWND  hwndDIg,  USHORT  usld) 


This  macro  returns  the  checked  state  of  the  button  control  specified. 

Parameters 

hwndDIg  (HWNO)  - input 
Dialog  window  handle. 

usld  (USHORT)  - input 
Button  control  identity. 


Returns 

Returns  the  checkstate  of  the  specified  button  control. 

Remarks 

This  macro  expands  to: 

Idefine  WinQueryButtonCheckstate (hwndDIg,  usld) 

( (USHORT) Wi nSendDl gl temMsg (hwndDl g , 

usld, 

BM_QUERYCHECK, 

(MPARAM) NULL, 
(MPARAM)NULL)) 

This  function  requires  the  existence  of  a message  queue. 

Related  Functions 

• WinSendDIgltemMsg 

Related  Messages 

• BM_QUERYCHECK 
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WinQueryButtonCheckstate  - 
Query  Checkstate  of  Button 


Example  Code 

This  function  returns  the  checked  state  of  the  button  control  specified. 


fdefine  INCL_WINWINOOWMGR 
finclude  <0S2.H> 
fdefine  IDM_BUTTONA  900 

HWNO  hwndDlg; 

USHORT  ChkState; 


ChkState  = WinQueryButtonCheckstate (hwndDlg, 

IDM_BUTTONA) ; 

switch  (ChkState) 

{ 


case  0: 

/*  Unchecked  */ 
break; 
case  1: 

/*  Checked  */ 
break; 
case  2: 

/*  Indeterminate.  */ 
break; 
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WinQueryCapture 
Query  Capture 


#define  INCL_WININPUT  /*  Or  use  INCL_WIN  or  INCL_PM  7 


HWND  WinQueryCapture  (HWND  hwndDesktop) 


This  function  returns  the  handle  of  the  window  that  has  the  pointer  captured. 

Parameters 

hwndDesktop  (HWND)  - input 
Desktop-window  handle: 

HWND  DESKTOP  The  desktop-window  handle 
Other  Specified  desktop-window  handle. 

Returns 

Handle  of  the  window  with  the  pointer  captured: 

NULLHANDLE  No  window  has  the  pointer  captured,  or  an  error  occurred 
Handle  Handle  of  the  window  with  the  pointer  captured. 

Possible  returns  from  WinGetLastError 

PMERRJNVALID  HWND  An  invalid  window  handle  was  specified. 

Related  Functions 

• WinSetCapture 

Example  Code 

This  function  returns  the  handle  of  the  window  that  has  the  pointer  captured. 


Idefine  INCL_WININPUT 
Idefine  INCLJIINWINDOWMGR 
linclude  <0S2.H> 

HWND  hwnd;  /*  handle  of  window  that  has  pointer  captured  */ 

hwnd  = WinQueryCapture (HWND_DESKTOP) ; /*  window  that  has  */ 

/*  pointer  captured  */ 
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WinQueryClassInfo  - 
Query  Class  Information 


#define  INCLJVINWINDOWMGR  /*  Or  use  INCL_WIN  or  INCL_PM  */ 


BOOL  WinQueryClassInfo  (HAB  hab,  PSZ  pszClassName,  PCLASSINFO  pcIsICiassInfo) 


This  function  returns  window  class  information. 

Parameters 

hab  (HAB)  - input 

Anchor-block  handle. 

pszClassName  (PSZ)  - input 
Class  name. 

pcIsICiassInfo  (PCLASSINFO)  - output 
Class  information  structure. 


Returns 

Class-exists  indicator: 

TRUE  Class  does  exist 
FALSE  Class  does  not  exist. 

Possible  returns  from  WinGetLastError 

PMERRINVALIDINTEGERATOM  The  specified  atom  is  not  a valid  integer  atom. 

PMERR_INVALID_ATOM_NAME  An  invalid  atom  name  string  was  passed. 

PMERR_ATOM_NAME_NOT_FOUND  The  specified  atom  name  is  not  in  the  atom  table. 

Remarks 

pszClassName  is  either  an  application-specified  name  (as  defined  by  the  WinRegisterClass  call)  or 
the  name  of  a preregistered  WC_*  class;  see  page  11-2.  Preregistered  class  names  are  of  the  form 
#nnnnn,  where  nnnnn  is  up  to  five  digits  corresponding  to  the  value  of  the  WC_*  class  name  constant. 

This  function  provides  information  that  is  needed  to  create  a subclass  of  a given  class  (see 
WinSubclassWindow). 


Related  Functions 

• WinCalcFrameRect 

• WinCreateFrameControls 

• WinCreateStdWindow 

• WinCreateWindow 

• WinDefWindowProc 

• WinDestroyWindow 

• WinQueryClassName 

• WinRegisterClass 

• WinSubclassWindow 
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WinQueryClassInfo  - 
Query  Class  Information 


Example  Code 

This  example  obtains  a pointer  to  the  window  procedure  of  the  window  class  WC_COMBOBOX. 

Idefine  INCL_WINWINDOWMGR 
fdefine  INCL_WINENTRYFIELDS 
linclude  <0S2.H> 

HAB  hab; 

/*  • */ 

CLASSINFO  classinfo; 

PFNWP  pWindowProc; 


WinQueryClassInfo(hab, 

WC_C0MB0B0X , 
&classinfo) ; 

pWindowProc  = classinfo.pfnWindowProc; 
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WinQueryClassName  - 
Query  Class  Name 


#define  INCL_WINWINDOWMGR  /*  Or  use  INCL_WIN  or  INCL_PM  */ 


LONG  WinQueryClassName  (HWND  hwnd,  LONG  ILength,  PCH  pchBuffer) 


This  function  copies  the  window  class  name,  as  a null-terminated  string,  into  a buffer. 


Parameters 

hwnd  (HWND)  - input 
Window  handle. 

If  this  window  is  of  any  of  the  preregistered  WC_*  classes  (see  page  11-2),  the  class  name 
returned  in  the  pchBuffer  parameter  is  in  the  form  “#nnnnn,”  where  “nnnnn”  is  a group  of  up  to 
five  digits  that  corresponds  to  the  value  of  the  WC_*  class  name  constant. 

ILength  (LONG)  - input 
Length  of  pchBuffer. 

pchBuffer  (PCH)  - output 
Class  name. 

If  the  class  name  is  longer  than  ( ILength — 1)  only  the  first  (ILength— 1 ) characters  of  class  name 
are  copied. 


Returns 

Returned  class  name  length. 

This  is  the  length,  excluding  the  null-termination  character. 


Possible  returns  from  WinGetLastError 

PMERR  INVALID  HWND 
PMERRINVALIDSTRINGPARM 

Related  Functions 

• WinCalcFrameRect 

• WinCreateFrameControls 

• WinCreateStdWindow 

• WinCreateWindow 

• WinDefWindowProc 

• WinDestroyWindow 

• WinQueryClassInfo 

• WinRegisterClass 

• WinSubclassWindow 


An  invalid  window  handle  was  specified. 
The  specified  string  parameter  is  invalid. 
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WinQueryClassName 
Query  Class  Name 


Example  Code 

This  example  obtains  a pointer  to  the  window  procedure  of  the  window  class,  given  that  we  know  the 
window  handle. 

fdefine  INCL_WINWINDOWMGR 
linclude  <0S2.H> 

HAB  hab; 

/*  . */ 

HWNO  hwnd; 

CLASSINFO  classinfo; 

PFNWP  pWindowProc; 
char  *classname; 


Wi nQueryCl assName (hwnd , 

si zeof (classname) , 
classname) ; 


WinQueryCl ass Info (hwnd, 

classname, 

&classinfo); 

pWindowProc  = classinfo.pfnWindowProc; 
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WinQueryClassThunkProc  - 
Query  Class  Pointer-Conversion  Procedure 


#define  INCL_WINTHUNKAPI  /*  Or  use  INCL.WIN  or  INCL_PM  */ 


PFN  WinQueryClassThunkProc  (PSZ  pszCiassName) 


This  call  queries  the  pointer-conversion  procedure  associated  with  a class. 


Parameters 

pszCiassName  (PSZ)  - input 
Window-class  name. 


Returns 

Pointer-conversion  procedure  identifier: 

NULL  No  pointer-conversion  procedure  is  associated  with  this  class. 

Other  Identifier  of  the  pointer-conversion  procedure  associated  with  this  class. 

Related  Functions 

• WinQueryWindowModel 

• WinQueryWindowThunkProc 

• WinSetClassThunkProc 

• WinSetWindowThunkProc 

Example  Code 

This  example  obtains  the  pointer  conversion  procedure  of  the  window  class,  given  that  we  have  an 
anchor-block  handle. 

fdefine  INCL_WINWINDOWMGR 
fdefine  INCL_WINTHUNKAPI 
finciude  <0S2.H> 

HWND  hwnd; 

/*  • */ 

PFN  pfn; 

char  *classname; 


Wi nQueryCI assName ( hwnd , 

sizeof(classname) , 
classname) ; 


pfn  = WinQueryClassThunkProc(classname) ; 
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WinQueryCI  ipbrd  Data 
Query  Clipboard  Data 


#define  INCL_WINCLIPBOARD  /*  Or  use  INCL_WIN  or  INCL_PM  */ 


ULONG  WinQueryClIpbrdData  (HAB  hab,  ULONG  ulfmt) 


This  function  obtains  a handle  to  the  current  clipboard  data  with  a specified  format. 


Parameters 

hab  (HAB)  - input 

Anchor-block  handle. 

ulfmt  (ULONG)  - input 

Format  of  the  data  to  be  accessed. 


Returns 

Handle  to  the  clipboard  data: 

0 Format  does  not  exist,  or  an  error  occurred 

Other  Handle  to  the  clipboard  data. 

Remarks 

The  returned  data  handle  must  not  be  used  after  the  WinCloseClipbrd  function  is  called.  For  this 
reason,  the  application  must  either  copy  the  data  (if  required  for  long-term  use)  or  process  the  data 
before  the  WinCloseClipbrd  function  is  called.  The  application  must  neither  free  the  data  handle 
itself,  nor  leave  it  locked  in  any  way. 

Information  about  the  format  of  the  data  in  the  clipboard  can  be  obtained  from 
WinQueryClipbrdFmtlnfo. 


Related  Functions 

• WinCloseClipbrd 

• WinEmptyClipbrd 

• WinEnumClipbrdFmts 

• WinOpenClipbrd 

• WinQueryClipbrdFmtlnfo 

• WinQueryClipbrdOwner 

• WinQueryClipbrdViewer 

• WinSetClipbrdData 

• WinSetClipbrdOwner 

• WinSetClipbrdViewer 
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WinQueryClipbrdData  - 
Query  Clipboard  Data 


Example  Code 

This  example  obtains  a handle  to  the  current  clipboard  data  of  text  format. 

Idefine  I NCL_W INCLIPBOARD 
linclude  <0S2.H> 

HAB  hab; 

/*  • */ 

ULONG  hclipbrdData; 


hclipbrdData  = WinQueryClipbrdData(hab, 

CF_TEXT) ; 
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WinQueryClipbrdFmtlnfo  - 
Query  Clipboard  Format  Information 


#define  INCL_WINCLIPBOARD  /*  Or  use  INCL_WIN  or  INCL_PM  */ 


BOOL  WlnQueryCiipbrdFmtlnfo  (HAB  hab,  ULONG  ulfmt,  PULONG  pulFmtlnfo) 


This  function  determines  whether  a particular  format  of  data  is  present  in  the  clipboard,  and  if  so, 
provides  information  about  that  format. 

Parameters 

hab  (HAB)  - input 

Anchor-block  handle. 

ulfmt  (ULONG)  - input 

Format  of  the  data  to  be  queried. 

pulFmtlnfo  (PULONG)  - output 

Memory  model  and  usage  flags. 

These  are  the  usage  flags  set  by  the  setting  application;  that  is,  the  CFI_*  flags  of  the  flFmtlnfo 
parameter  of  the  WinSetClipbrdData  function. 

If  the  format  is  CF_BITMAP,  CF_DSPBITMAP,  CF_METAFILE  or  CF_DSPMETAFILE,  pulFmtlnfo  is 
set  to  CFI_HANDLE.  If  the  format  is  CF_TEXT  or  CF_DSPTEXT,  pulFmtlnfo  is  set  to  CFI_POINTER. 
If  the  format  is  user-defined,  pulFmtlnfo  is  set  to  the  value  used  in  the  WinSetClipbrdData 
function. 

Returns 

Format-exists  indicator: 

TRUE  ulfmt  exists  in  the  clipboard  and  pulFmtlnfo  is  set 

FALSE  ulfmt  does  not  exist  in  the  clipboard  and  pulFmtlnfo  is  not  set. 

Possible  returns  from  WinGetLastError 

PM ERRJNV ALID  FLAG  An  invalid  bit  was  set  for  a parameter.  Use  constants 

defined  by  PM  for  options,  and  do  not  set  any  reserved 
bits. 


Remarks 

This  function  does  not  cause  the  data  to  be  rendered. 

Related  Functions 

• WinCloseClipbrd 

• WinEmptyClipbrd 

• WinEnumClipbrdFmts 

• WinOpenClipbrd 

• WinQueryClipbrdData 

• WinQueryClipbrdOwner 

• WinQueryClipbrdViewer 

• WinSetClipbrdData 

• WinSetClipbrdOwner 

• WinSetClipbrdViewer 
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WinQueryClipbrdFmtlnfo  - 
Query  Clipboard  Format  Information 


Example  Code 

This  example  obtains  a handle  to  the  current  clipboard  data  of  text  format  if  that  format  is  present  in 
the  clipboard. 

Idefine  INCL_WINCLIPBOARD 
finclude  <0S2.H> 

HAB  hab; 

/*  . */ 

ULONG  format; 

ULONG  hclipbrdData; 


if  (WinQueryCl ipbrdData(hab,CF_TEXT)) 

{ 

hclipbrdData  = WinQueryCl ipbrdFmfInfo(hab, 

CF_TEXT 
Sformat) ; 

} 
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WinQueryClipbrdOwner 
Query  Clipboard  Owner 


#define  INCL_WINCLIPBOARD  /*  Or  use  INCL_WIN  or  INCL_PM  7 


HWND  WinQueryClipbrdOwner  (HAB  hab) 


This  function  obtains  any  current  clipboard  owner  window. 

Parameters 

hab  (HAB)  - input 

Anchor-block  handle. 


Returns 

Window  handle  of  the  current  clipboard  owner: 

NULLHANDLE  If  the  clipboard  is  not  owned  by  any  window,  or  if  an  error  occurred. 
Other  Window  handle  of  the  current  clipboard  owner. 

Related  Functions 

• WinCloseClipbrd 

• WinEmptyClipbrd 

• WinEnumClipbrdFmts 

• WinOpenClipbrd 

• WinQueryClipbrdOata 

• WinQueryClipbrdFmtlnfo 

• WinQueryClipbrdViewer 

• WinSetClipbrdData 

• WinSetClipbrdOwner 

• WinSetClipbrdViewer 

Example  Code 

This  example  finds  out  which  window  currently  owns  the  clipboard. 

fdefine  INCL_WINCLIPBOARD 
#include  <0S2.H> 

HAB  hab; 

/*  • */ 

HWND  hwndCl i pbrdOwner ; 

hwndCiipbrdOwner  = WinQueryClipbrdOwner (hab); 
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WinQueryClipbrdViewer  - 
Query  Clipboard  Viewer 


#define  INCL_WINCLIPBOARD  /*  Or  use  INCL_WIN  or  INCL_PM  */ 


HWND  WinQueryClipbrdViewer  (HAB  hab) 


This  function  obtains  any  current  clipboard  viewer  window. 


Parameters 

hab  (HAB)  - input 

Anchor-block  handle. 


Returns 

Current  clipboard  viewer  window  handle: 

NULLHANDLE  Clipboard  does  not  have  a current  viewer  window,  or  an  error  occurred 
Other  Current  clipboard  viewer  window  handle. 

Related  Functions 

• WinCloseClipbrd 

• WinEmptyClipbrd 

• WinEnumClipbrdFmts 

• WinOpenClipbrd 

• WinQueryClipbrdData 

• WinQueryClipbrdFmtlnfo 

• WinQueryClipbrdOwner 

• WinSetClipbrdData 

• WinSetClipbrdOwner 

• WinSetClipbrdViewer 

Example  Code 

This  example  finds  out  which  window  currently  owns  the  clipboard. 

#define  I NCL_W INCLIPBOARD 
#include  <0S2.H> 

HAB  hab; 

/*  . */ 

HWND  hwndCl ipbrdViewer; 

hwndClipbrdViewer  = WinQueryClipbrdViewer(hab); 
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WinQueryCp  - 
Query  Code  Page 


#define  INCL_WINCOUNTRY  /*  Or  use  INCL_WIN  or  INCL_PM  7 


ULONG  WinQueryCp  (HMQ  hmq) 


This  function  returns  the  queue  code  page  for  the  specified  message  queue. 

Parameters 

hmq  (HMQ)  - input 
Message  queue. 


Returns 

Code  page: 

0 Error  occurred 

Other  Queue  code  page  for  the  specified  message  queue. 

Possible  returns  from  WinGetLastError 

PMERR  INVALID  HMQ  An  invalid  message-queue  handle  was  specified. 

Related  Functions 

• WinCpTranslateChar 

• WinCpTranslateString 

• WinQueryCpList 

• WinSetCp 

Example  Code 

This  example  returns  the  queue  code  page  for  the  specified  queue. 

Idefine  INCL_WINCOUNTRY 
finclude  <0S2.H> 

HMQ  hmq; 

/*  . */ 

ULONG  cp; 

cp  = WinQueryCp(hmq) ; 


8-314 


PM  Programming  Reference 


WinQueryCpList  - 
Query  Code  Page  List 


#define  INCL_WINCOUNTRY  /*  Or  use  INCL.WIN  or  INCL_PM  */ 


ULONG  WinQueryCpList  (HAB  hab,  ULONG  ulcount,  PULONG  aulCodepage) 


This  function  queries  available  code  pages. 

Parameters 

hab  (HAB)  - input 

Anchor-block  handle. 

ulcount  (ULONG)  - input 

Maximum  number  of  code  pages  returned. 

aulCodepage  (PULONG)  - output 
Code  page  list. 

An  array  of  ulcount  elements,  that  contains  a list  of  code  pages  available  to  the  program. 

For  more  information  about  code  pages,  see  Chapter  34,  “Code  Pages”  on  page  34-1. 

Returns 

Total  number  of  code  pages  available: 

0 An  error  occurred 

Other  Total  number  of  code  pages  available. 

Possible  returns  from  WinGetLastError 

PMERR_PARAMETER_OUT_OF_RANGE  The  value  of  a parameter  was  not  within  the  defined  valid 

range  for  that  parameter. 


Related  Functions 

• WinCpTranslateChar 

• WinCpTranslateString 

• WinQueryCp 

• WinSetCp 

Example  Code 

This  example  queries  available  code  pages. 

#define  INCL_WINCOUNTRY 
linclude  <0S2.H> 

Idefine  maxcount  8 
HAB  hab; 

/*  . */ 

ULONG  aul Codepage [maxcount] ; 


WinQueryCpList  (hab, 

(ULONG)maxcount, 
(PULONG)  aulCodepage); 
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WinQueryCursorlnfo  - 
Query  Cursor  Information 


#define  INCL_WINCURSORS  /*  Or  use  INCL_WIN  or  INCL_PM  */ 


BOOL  WinQueryCursorlnfo  (HWND  hwndDeskTop,  PCURSORINFO  pcsrlCursorlnfo) 


This  function  obtains  information  about  any  current  cursor. 


Parameters 

hwndDeskTop  (HWND)  - input 
Desktop-window  handle: 

HWND_DESKTOP  The  desktop-window  handle 

Other  Specified  desktop-window  handle. 

pcsrlCursorlnfo  (PCURSORINFO)  - output 
Cursor  information. 

The  values  are  equivalent  to  the  parameters  of  the  WinCreateCursor  function  except  that  ulrgf 
never  includes  the  CURSOR_SETPOS  option. 

The  size  and  position  of  the  cursor  are  returned  in  window  coordinates  relative  to  the  window 
identified  by  the  hwnd  parameter  of  the  structure. 


Returns 

Current-cursor  indicator: 

TRUE  Cursor  exists 

FALSE  Cursor  does  not  exist,  pcsrlCursorlnfo  is  not  updated  by  this  call. 
Possible  returns  from  WinGetLastError 

PMERR  INVALID  HWND  An  invalid  window  handle  was  specified. 

Related  Functions 

• WinCreateCursor 

• WinDestroyCursor 

• WinShowCursor 

Example  Code 

This  example  obtains  information  about  any  current  cursor. 

Idefine  INCL_WINCURSORS 
Idefine  INCL_WINWINDOWMGR 
finclude  <0S2.H> 

HWND  hwnd;  /*  handle  of  window  that  has  pointer  captured  */ 

CURSORINFO  cursorinfo; 

WinQueryCursorInfo(hwnd_DESKTOP,  /*  get  cursor  info  */ 

Scursorinfo); 
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WinQueryDesktopBkgnd  - 
Query  Desktop  Background 


#define  INCL_WINWINDOWMGR  /*  Or  use  INCL_WIN  or  INCL_PM  */ 


BOOL  WinQueryDesktopBkgnd  (HWND  hwndDeskTop,  PDESKTOP  pDeskTopState) 


This  function  returns  the  desktop  structure,  which  contains  the  information  about  the  current  state  of 
the  desktop  background. 


Parameters 

hwndDeskTop  (HWND)  - input 
Desktop-window  handle. 

HWND_DESKTOP  The  desktop  window 

Other  Specified  desktop  window. 

pDeskTopState  (PDESKTOP)  - output 
Desktop-state  structure. 


Returns 

Success  indicator: 

TRUE  Desktop-window  status  provided 
FALSE  Desktop- window  status  not  provided. 

Possible  returns  from  WinGetLastError 

PMERR  INVALID  HWND  An  invalid  window  handle  was  specified. 

Remarks 

This  function  allows  an  application  to  query  the  background  information  of  the  desktop  window.  This 
application  must  be  acting  as  the  OS/2  PM  shell  in  place  of  the  IBM  supplied  shell.  If  the  IBM 
supplied  shell  is  executing  it  maintains  control  of  the  background  of  the  desktop  window,  and 
WinQueryDesktopBkgnd  will  have  no  effect  on  the  desktop  window  background,  but  will  indicate  a 
successful  return  code. 

Related  Functions 

• WinSetDesktopBkgnd 
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WinQueryDesktopBkgnd  - 
Query  Desktop  Background 


Example  Code 

This  example  uses  WinQueryDesktopBkgnd  to  query  the  current  desktop  background  bit  map  before 
setting  it  to  a new  bit  map  with  WinSetDesktopBkgnd. 

Idefine  INCL_WINDESKTOP 
fdefine  INCL_WINWINDOWMGR 
linclude  <0S2.H> 

HAB  hab; 

HWND  hwndDeskTop; 

DESKTOP  DeskTopState; 

HBITMAP  hbm; 

HBITMAP  hbm_user; 


WinQueryDesktopBkgnd(HWND_DESKTOP, 
&DeskTopState) ; 

if  (hbm_user  !=  DeskTopState. hbm) 

{ 


DeskTopState.fi  = SDT_LOADFILE; 

/*  the  szFile  is  used  to  load  the  bit  map  because  */ 
/*  the  fl  parameter  is  set  to  SDT_LOADFILE.  */ 
strcpy (DeskTopState. szFile, "fruit. bmp" ) ; 

DeskTopState. hbm  = hbm_user; 

WinSetDesktopBkgnd(hwndDeskTop, 

&DeskTopState) ; 


} 
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WinQuery  Desktop  Window  - 
Query  Desktop  Window 


#define  INCL_WINWINDOWMGR  /*  Or  use  INCL_WIN  or  INCL_PM  7 


HWND  WlnQueryDesktopWindow  (HAB  hab,  HOC  hdc) 


This  function  returns  the  desktop-window  handle. 

Parameters 

hab  (HAB)  - input 

Anchor-block  handle. 

hdc  (HOC)  - input 

Device-context  handle: 

NULLHANOLE  Default  device  (the  screen). 

Returns 

Desktop-window  handle: 

NULLHANOLE  Error  occurred 
Other  Desktop-window  handle. 

Possible  returns  from  WinGetLastError 

PMERRINVHDC  An  invalid  device-context  handle  or  (micro  presentation 

space)  presentation-space  handle  was  specified. 

Remarks 

Only  the  screen  device  supports  windowing. 

Many  of  the  calls  that  require  a desktop-window  handle  accept  HWND_DESKT OP  instead.  For 
example,  WinCreateWindow  accepts  HWND_DESKTOP  for  the  parent-window  handle  to  create  a main 
window  that  is  a child  of  the  desktop  window. 


Related  Functions 

• WinEnableWindow 

• WinlsThreadActive 

• WinlsWindow 

• WinlsWindowEnabled 

• WinQueryObjectWindow 

• WinQueryWindowDC 

• WinQueryWindowProcess 

• WinQueryWindowRect 

• WinWindowFromDC 

• WinWindowFromID 

• WinWindowFromPoint 
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WinQueryDesktopWindow 
Query  Desktop  Window 


Example  Code 

This  function  is  used  to  find  the  desktop  window  handle.  For  most  calls  however,  the  parameter 
HWND_DESKTOP  can  be  used. 

Idefine  INCL_WINDESKTOP 
linclude  <0S2.H> 

HAB  hab; 

HWND  hwndDeskTop; 

hwndDeskTop  = WinQueryDesktopWindow(hab, 

NULLHANDLE) ; 
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WinQueryDIgltemShort  - 
Query  Dialog  Item  Short 


#define  INCL_WINDIALOGS  /*  Or  use  INCL_WIN  or  INCL_PM.  Also  in  COMMON  section  */ 


BOOL  WinQueryDIgltemShort  (HWND  hwndDIg,  ULONG  Idltem,  PSHORT  psResult, 

BOOL  (Signed) 


This  function  converts  the  text  of  a dialog  item  into  an  integer  value. 


Parameters 

hwndDIg  (HWND)  - input 
Parent-window  handle. 

Idltem  (ULONG)  - input 

Identity  of  the  child  window  whose  text  is  to  be  converted. 

psResult  (PSHORT)  - output 

Integer  value  resulting  from  the  conversion. 

(Signed  (BOOL)  - input 
Sign  indicator: 

TRUE  Signed  text.  It  is  inspected  for  a minus  sign  (— ). 

FALSE  Unsigned  text. 

Returns 

Success  indicator: 

TRUE  Successful  conversion 
FALSE  Error  occurred. 

Possible  returns  from  WinGetLastError 

PMERR  INVALID  HWND  An  invalid  window  handle  was  specified. 

Remarks 

This  function  is  useful  for  converting  a numerical  input  field  into  a binary  number  for  further 
processing.  The  text  of  a dialog  item  is  assumed  to  be  an  ASCII  string. 

This  function  is  valid  for  any  window  with  children.  However,  it  is  typically  used  for  dialog  items  in  a 
dialog  window. 


Related  Functions 

• WinQueryDIgltemText 

• WinQueryDIgltemTextLength 

• WinQueryWindowText 

• WinQueryWindowTextLength 

• WinSetDIgltemShort 

• WinSetDIgltemText 

• WinSetWindowText 
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WinQueryDIgltemShort 
Query  Dialog  Item  Short 


Example  Code 

This  example  gets  the  text  from  a Dialog  Box  entry  field  as  an  integer  value. 

Idefine  INCL_WINDIALOGS 
linclude  <0S2.H> 

Idefine  ID_ENTRYFLD  900 
HAB  hab; 

HWND  hwnd; 

ULONG  msg; 

MPARAM  mpl; 

SHORT  i converted; 

/*•  * / 
switch(msg) 

{ 

case  WM  INITDLG: 

case  WM_COMMAND : 
switch (SH0RT1FR0MMP (mpl ) ) 

{ 

case  DID_0K: 

Wi nQueryDl g I temShort ( hwnd , 

ID_ENTRYFLD, 

&i converted,  /*  integer  result  */ 

TRUE);  /*  Get  the  short  */ 


} 

} 
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WinQueryDIgltemText  - 
Query  Dialog  Item  Text 


#define  INCL_WINDIALOGS  /*  Or  use  INCL_WIN  or  INCL_PM.  Also  in  COMMON  section  */ 


ULONG  WinQueryDIgltemText  (HWND  hwndDIg,  ULONG  Idltem,  LONG  IMaxText,  PSZ  pszText) 


This  function  queries  a text  string  in  a dialog  item. 


Parameters 

hwndDIg  (HWND)  - input 
Parent-window  handle. 

Idltem  (ULONG)  - input 

Identity  of  the  child  window  whose  text  is  to  be  queried. 

IMaxText  (LONG)  - input 
Length  of  pszText. 

pszText  (PSZ)  - output 
Output  string. 

This  is  the  text  string  that  is  obtained  from  the  dialog  Item. 


Returns 

Actual  number  of  characters  returned: 

0 Error  occurred 

Other  Actual  number  of  characters  returned,  not  including  the  null-terminating  character.  The 
maximum  value  Is  (IMaxText—  1). 

Possible  returns  from  WinGetLastError 

PMERR  INVALID  HWND  An  invalid  window  handle  was  specified. 

Remarks 

This  function  is  valid  for  any  window  with  children.  However,  it  is  typically  used  for  dialog  items  in  a 
dialog  window. 


Related  Functions 

• WinQueryDIgltemShort 

• WinQueryDIgltemTextLength 

• WinQueryWindowText 

• WinQueryWindowTextLength 

• WinSetDIgltemShort 

• WinSetDIgltemText 

• WinSetWindowText 


Chapter  8.  Window  Functions  8-323 


WinQuery  DlgltemT  ext 
Query  Dialog  Item  Text 


Example  Code 

This  example  is  the  beginning  of  a function  which  processes  the  text  which  is  displayed  in  the 
message  text  line. 

#define  INCL_WINDIALOGS 
linclude  <0S2.H> 
fdefine  DID_MSGEDIT  900 
void  SelectMessageFromText( hwndDlg) 

HWND  hwndDlg; 

{ 

char  szTemp[80]; 

/*  First  get  the  edit  text  from  the  string  */ 

Wi  nQuery  Dig  I temText(  hwndDlg,  DIDMSGEDIT,  sizeof(szTemp) , 

(PSZ)szTemp) ; 

/*  . */ 

/*  • */ 

} 
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WinQueryDIgltemTextLength  - 
Query  Dialog  Item  Text  Length 


#define  INCL_WINDIALOGS  /*  Or  use  INCL_WIN  or  INCL_PM.  Also  in  COMMON  section  */ 


LONG  WinQueryDIgltemTextLength  (HWND  hwndDIg,  ULONG  idltem) 


This  function  queries  the  length  of  the  text  string  in  a dialog  item,  not  including  any  null  termination 
character. 

Parameters 

hwndDIg  (HWND)  - input 
Parent-window  handle. 

Idltem  (ULONG)  - input 

Identity  of  the  child  window  whose  text  is  to  be  queried. 


Returns 

Length  of  text: 

0 Error  occurred 

Other  Length  of  text. 

Remarks 

This  function  is  valid  for  any  window  with  children.  However,  it  is  typically  used  for  dialog  items  in  a 
dialog  window. 

Related  Functions 

• WinQueryDIgltemShort 

• WinQueryDIgltemText 

• WinQueryWindowText 

• WinQueryWindowTextLength 

• WinSetDIgltemShort 

• WinSetDIgltemText 

• WinSetWindowText 
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WinQueryDIgltemTextLength  - 
Query  Dialog  Item  Text  Length 


Example  Code 

This  example  is  the  beginning  of  a function  which  processes  the  text  which  is  displayed  in  the 
message  text  line. 

fdefine  I NCL_WINDIALOGS 

fdefine  INCL_DOSMEMMGR 

finclude  <0S2.H> 

fdefine  DID.MSGEDIT  900 

void  Sel ectMessageFromText ( hwndDl g) 

HWND  hwndDl g; 

{ 

char  *szTemp; 

LONG  length; 

/*  First  get  the  edit  text  from  the  string  */ 

length  = WinQueryDIgltemTextLength (hwndDl g, 

DID_MSGEDIT); 

/*  now  we  know  the  buffer  size  needed.  */ 

DosAllocMem((PPVOID)szTemp, 

(ULONG) length, 

PAG_READ  | 

PAG_WRITE  | 

PAG_COMMIT) ; 

Wi nQueryDl gltemText (hwndDl g , 

DID_MSGEDIT, 
sizeof(szTemp) , 

(PSZ)szTemp) ; 

/*  • */ 

/*  • */ 

} 
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WinQueryFocus  - 
Query  Focus 


^define  INCL_WININPUT  /*  Or  use  INCL_WIN  or  INCL_PM  7 


HWND  WinQueryFocus  (HWNO  hwndDeskTop) 


This  function  returns  the  focus  window.  It  is  NULLHANDLE  if  there  is  no  focus  window. 


Parameters 

hwndDeskTop  (HWND)  - input 
Desktop-window  handle: 

HWND  DESKTOP  The  desktop-window  handle 
Other  Specified  desktop-window  handle. 


Returns 

Focus-handle. 


NULL  Error  occurred  or  no  focus  window. 

Possible  returns  from  WinGetLastError 

PMERR  INVALID  HWND  An  invalid  window  handle  was  specified. 

Related  Functions 

• WinEnablePhysinput 

• WinFocusChange 

• WinGetKeyState 

• WinGetPhysKeyState 

• WinSetFocus 

• WinSetKeyboardStateTable 

Example  Code 

This  example  checks  to  see  if  the  menu  has  the  focus. 

Idefine  INCL_WININPUT 
linclude  <0S2.H> 

Idefine  SYS_MENU  900 
HWND  hwndFrame; 

if  (WinQueryFocus (HWND_DESKTOP)  == 

WinWindowFromID(hwndFrame,  SYS_MENU) ) 

{ 

/*  • */ 

} 
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WinQueryHelpInstance  - 
Query  Help  Instance 


#define  INCL_WINHELP  /*  Or  use  INCL_WIN  or  INCL_PM  7 


HWND  WinQueryHelpInstance  (HWND  hwndApp) 


This  function  enables  the  application  to  query  the  instance  of  the  help  manager  associated  with  the 
application-supplied  window  handle. 


Parameters 

hwndApp  (HWND)  - input 

Handle  of  the  application  window. 


Returns 

Help  manager  window  handle: 

NULLHANDLE  No  help  manager  instance  is  associated  with  the  application  window. 

Other  Help  manager  window  handle. 

Remarks 

The  help  manager  first  traces  the  parent  window  chain  until  it  is  NULLHANDLE  or  HWND_DESKTOP. 
Then  help  manager  traces  the  owner  chain.  If  a parent  of  tfte  owner  window  exists,  the  trace  begins 
again  with  the  parent  chain. 

The  window  chain  will  be  traced  until  the  help  manager  finds  an  instance  of  the  help  manager  or  until 
both  the  parent  and  owner  windows  are  NULLHANDLE  or  HWND_DESKTOP. 


Related  Functions 

• WinAssociateHelpInstance 

• WinCreateHelpinstance 

• WinCreateHelpTable 

• WinDestroyHelpinstance 

• WinLoadHelpTable 
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WinQueryHelpInstance  - 
Query  Help  Instance 


Example  Code 

This  example  shows  the  use  of  the  WinQueryHelpInstance  call  during  the  processing  of  a 
WM  INITMENU  message  in  order  to  obtain  the  handle  for  sending  an  HM_SET_ACTIVE_WINDOW 
message. 

#define  INCL_WIN 
#include  <os2.h> 

MRESULT  wm_initinenu(  HWND  hWnd,  ULONG  ulMsg,  MPARAM  mpl,  MPARAM 

{ 

/*  Send  message  to  establish  the  current  window's  parent 
/*  as  the  active  help  window. 

WinSendMsg(  WinQueryHelpInstance(  hWnd  ), 

HM_SET_ACTIVE_WINDOW, 

(MPARAM)WinQueryWindow(  hWnd,  QW_PARENT  ), 

(MPARAM) WinQueryWindow(  hWnd,  QW_PARENT  ) ); 

/*  Pass  message  on  for  default  processing  */ 

return  WinDefWindowProc(  hWnd,  ulMsg,  mpl,  mp2  ); 


mp2  ) 

*/ 

*/ 
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WinQueryLboxCount  - 
Counts  Number  of  Items  in  Listbox 


#define  INCL_WINWINDOWMGR  /*  Or  use  INCL_WIN  or  INCL_PM  */ 


SHORT  WinQueryLboxCount  (HWND  hwndLbox) 


This  macro  returns  the  number  of  items  in  the  List  Box. 

Parameters 

hwndLbox  (HWND)  - input 
Listbox  handle. 


Returns 

Number  of  items  in  the  list  box. 


Remarks 

This  macro  expands  to: 

#def i ne  Wi nQuery LboxCount ( hwndLbox) 

( (SHORT)WinSendMsg(hwndLbox, 

LM_QUERYITEMCOUNT , 

(MPARAM)NULL, 

(MPARAM)NULL)) 

This  function  requires  the  existence  of  a message  queue. 


Related  Functions 

• WinSendMsg 

Related  Messages 

• LM  QUERYITEMCOUNT 


Example  Code 

This  example  uses  WinQueryLboxCount  to  find  the  number  of  list  box  items  and  selects  them  all. 

Idefine  INCL_WINLISTBOXES 
Idefine  INCL_WINWINDOWMGR 
linclude  <0S2.H> 

SHORT  cWindows; 

HWND  hwndWindowLB; 

cWindows  = WinQueryLboxCount(hwndWindowLB) ; 
while  (cWindows) 

{ 

/*  Loop  through  all  windows,  selecting  all  */ 

Wi nSendMsg (hwndWi ndowLB , 

LM_SELECTITEM, 

(MPARAM) -cWindows, 

(MPARAM)TRUE) ; 

} 
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WinQueryLboxItemText  - 
Query  Listbox  Item  Text 


#define  INCL_WINWINDOWMGR  /*  Or  use  INCL_WIN  or  INCL_PM  7 


SHORT  WinQueryLboxItemText  (HWND  hwndLbox,  SHORT  slndex,  PSZ  pszText, 

SHORT  scchMax) 


This  macro  fills  the  buffer  with  the  text  of  the  indexed  item.  It  returns  the  length  of  the  text. 


Parameters 

hwndLbox  (HWND)  - input 
List  box  handle. 

slndex  (SHORT)  - input 
Index  of  the  listbox  item. 

pszText  (PSZ)  - input 

Pointer  to  a null  terminated  string. 

scchMax  (SHORT)  - input 

Maximum  number  of  characters  allocated  to  the  string. 


Returns 

Actual  text  length  copied. 

Remarks 

This  macro  expands  to: 

Idefine  WinQueryLboxItemText(hwndLbox,  slndex,  pszText,  scchMax) 
( (SHORT) Wi nSendMs  g ( hwnd  Lbox , 

LMQUERYITEMTEXT, 

MPFR0M2SH0RT ( (slndex) , (scchMax)) , 
MPFROMP(pszText))) 

This  function  requires  the  existence  of  a message  queue. 

Related  Functions 

• WinSendMsg 

Related  Messages 

• LM  INSERTITEM 
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WinQueryLboxItemText 
Query  Listbox  Item  Text 


Example  Code 

This  example  uses  WinQueryLboxItemText  to  copy  all  of  the  list  box  items  into  a buffer. 

Idefine  INCL_WINLISTBOXES 
Idefine  INCL_WINWINDOWMGR 
linclude  <0S2.H> 

SHORT  cWindows; 
char  *szTemp; 

HWND  hwndLB; 

SHORT  maxchar,  index  = 0; 

cWindows  = WinQueryLboxCount(hwndLB) ; 

/*  allocate  a buffer  for  cWindows  items.  */ 

DosAl 1 ocMem( (PPVOID)&szTemp, 

(ULONG)cWi ndows*256*si zeof (char) , 

PAG_READ  | 

PAG_WRITE  | 

PAG_COMMIT) ; 

/*  loop  through  all  of  the  items;  copying  each.*/ 

/*  one  the  buffer.  */ 

while  (index  <=  cWindows) 

{ 


maxchar  = WinQueryLboxItemTextLength(hwndLB, index) ; 

WinQueryLboxItemText ( hwndLB , 
index++, 
szTemp, 
maxchar) ; 

(*szTemp)+=maxchar*sizeof(char) ; /*  increment  pointer  by  number  */ 

/*  of  bytes  copied.  */ 


} 
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WinQueryLboxItemText Length  - 
Query  Listbox  Item  Text  Length 


#define  INCL_WINWINDOWMGR  /*  Or  use  INCL_WIN  or  INCL_PM  */ 


SHORT  WinQueryLboxItemTextLength  (HWND  hwndLbox,  SHORT  slndex) 


This  macro  returns  the  length  of  the  text  of  the  indexed  item  in  the  List  Box. 


Parameters 

hwndLbox  (HWND)  - input 
Listbox  handle. 

sindex  (SHORT)  - input 

Index  of  the  item  in  the  List  Box. 


Returns 

Text  length  of  the  indexed  item. 


Remarks 

This  macro  expands  to: 

#define  WinQueryLboxItemTextLength (hwndLbox,  slndex) 

( (SHORT) Wi nSendMsg ( hwndLbox , 

LM_QUERY ITEMTEXTLENGTH , 
MPFROMSHORT(sIndex) , 
(MPARAM)NULL)) 

This  function  requires  the  existence  of  a message  queue. 


Related  Functions 

• Wi  nSendMsg 

Related  Messages 

• LM  QUERYITEMTEXTLENGTH 
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WinQuery  LboxItemT  extLength 
Query  Listbox  Item  Text  Length 


Example  Code 

This  example  uses  WinQueryLboxItemText  to  copy  all  of  the  list  box  items  into  a buffer. 

#define  INCL_WINLISTBOXES 
Idefine  INCL_WINWINDOWMGR 
#include  <0S2.H> 

SHORT  cWindows; 
char  *szTemp; 

HWND  hwndLB; 

SHORT  maxchar,  index  = 0; 

cWindows  = WinQueryLboxCount(hwndLB) ; 

/*  allocate  a buffer  for  cWindows  items.  */ 

DosAl locMem( (PPV0ID)&szTemp, 

(ULONG)cWi ndows*256*si zeof (char) , 

PAG_READ  | 

PAG_WRITE  | 

PAG_C0MMIT) ; 

/*  loop  through  all  of  the  items;  copying  each  */ 

/*  one  the  buffer.  */ 

while  (index  <=  cWindows) 

{ 


maxchar  = Wi nQueryLboxItemTextLength (hwndLB, i ndex) ; 

WinQueryLboxItemText (hwndLB, 
index++, 
szTemp, 
maxchar) ; 

(*szTemp)+=maxchar*si zeof (char) ; /*  increment  pointer  by  number  */ 

/*  of  bytes  copied.  */ 


} 
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WinQueryLboxSelectedltem  - 
Query  the  Selected  Item  in  Listbox 


#define  INCL_WINWINDOWMGR  /*  Or  use  INCL_WIN  or  INCL_PM  */ 


SHORT  WinQueryLboxSelectedltem  (HWND  hwndLbox) 


This  macro  returns  the  index  of  the  selected  item  in  the  List  Box  (for  single  selection  only). 

Parameters 

hwndLbox  (HWND)  - input 
List  box  handle. 


Returns 

Index  of  the  selected  item. 


Remarks 

This  macro  expands  to: 

fdefine  WinQueryLBoxSelectedltem  (hwndLbox) 

( (SHORT)Wi nSendMsg ( hwndLbox , 

LM_QUERYSELECTION , 
MPFROMSHORT(LIT_FIRST) , 
(MPARAM)NULL)) 

This  function  requires  the  existence  of  a message  queue. 


Related  Functions 

• WinSendMsg 

Related  Messages 

• LM  QUERYSELECTION 


Example  Code 

This  example  copies  the  text  from  the  selected  item  in  a list  box  to  a buffer. 

fdefine  INCL_WINLISTBOXES 
fdefine  INCLJIINWINDOWMGR 
finclude  <0S2.H> 

HWND  hwndLB; 

SHORT  index; 
char  szTemp[256] ; 

index  = WinQueryLboxSelectedltem(hwndLB) ; 

WinQueryLboxItemText (hwndLB, 
index, 
szTemp, 

Wi nQueryLboxItemTextLength ( hwndLB, i ndex) ) ; 
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WinQueryMsgPos  - 
Query  Message  Position 


#define  INCL_W1NMESSAGEMGR  /*  Or  use  INCL_WIN  or  INCL_PM  */ 


BOOL  WinQueryMsgPos  (HAB  hab,  PPOINTL  pptlptrpos) 


This  function  returns  the  pointer  position,  in  screen  coordinates,  when  the  last  message  obtained 
from  the  current  message  queue  is  posted. 


Parameters 

hab  (HAB)  - input 

Anchor-block  handle. 

pptlptrpos  (PPOINTL)  - output 

Pointer  position  in  screen  coordinates. 


Returns 

Success  indicator: 

TRUE  Successful  completion 
FALSE  Error  occurred. 

Remarks 

The  pointer  position  is  the  same  as  that  in  the  ptl  parameter  of  a QMSG  structure. 
To  obtain  the  current  position  of  the  pointer,  use  the  WinQueryPointerPos  function. 


Related  Functions 

• WinBroadcastMsg 

• WinCreateMsgQueue 

• WinDestroyMsgQueue 

• WinDispatchMsg 

• WinGetDIgMsg 

• WinGetMsg 

• WinlnSendMsg 

• WinPeekMsg 

• WinPostMsg 

• WinPostQueueMsg 

• WinQueryMsgTime 

• WinQueryQueuelnfo 

• WinQueryQueueStatus 

• WinRegisterllserDatatype 

• WinRegisterllserMsg 

• WinSendDIgltemMsg 

• WinSendMsg 

• WinSetClassMsglnterest 

• WinSetMsglnterest 

• WinSetMsgMode 

• WinSetSynchroMode 

• WinWaitMsg 
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WinQueryMsgPos  - 
Query  Message  Position 


Example  Code 

This  example  returns  position  and  time  of  the  the  last  message  obtained  from  the  current  message 
queue. 

Idefine  I NC L_WI NMESSAGEMGR 
#define  INCLJIINDIALOGS 
linclude  <0S2.H> 
linclude  <stdio.h> 

HAB  hab; 

POINTL  ptl ; 

CHAR  szMsg[100] ; 

HWND  hwnd; 

ULONG  ulTime; 


WinQueryMsgPos (hab,  &ptl ) ; 


ulTime  = WinQueryMsgTime(hab); 


sprintf(szMsg,  "x  = %ld  y = %ld\n\ntime  = %ld", 
ptl.x,  ptl.y,  ulTime); 

Wi nMessageBox ( HWND_0ESKT0P , 

hwnd,  /*  client-window  handle 

szMsg,  /*  body  of  the  message 

"Debugging  information",  /*  title  of  the  message 

0,  /*  message  box  id 

MB_N0IC0N  | MB_0K);  /*  icon  and  button  flags 


*/ 

*/ 

*/ 

*/ 

*/ 
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WinQueryMsgTime  - 
Query  Message  Time 


#define  INCL_WINMESSAGEMGR  /*  Or  use  INCL_WIN  or  INCL_PM  */ 


ULONG  WinQueryMsgTime  (HAB  hab) 


This  function  returns  the  message  time  for  the  last  message  retrieved  by  the  WinGetMsg  or 
WinPeekMsg  functions  from  the  current  message  queue. 


Parameters 

hab  (HAB)  - input 

Anchor-block  handle. 


Returns 

Time  in  milliseconds. 

Remarks 

The  message  time  is  the  time  the  message  is  posted,  measured  in  milliseconds,  from  the  time  the 
system  is  started.  Its  value  is  the  same  as  that  in  the  time  parameter  of  the  QMSG  structure. 

To  calculate  time  delays  between  messages,  the  time  of  the  first  message  is  subtracted  from  the 
time  of  the  second  message. 

Time  values  do  not  always  increase  because  the  value  is  the  number  of  milliseconds  since  the 
system  was  started,  and  the  system  accumulator  for  this  count  can  wrap  through  zero. 


Related  Functions 

• WinBroadcastMsg 

• WinCreateMsgQueue 

• WinDestroyMsgQueue 

• WinDispatchMsg 

• WinGetDIgMsg 

• WinGetMsg 

• WinlnSendMsg 

• WinPeekMsg 

• WinPostMsg 

• WinPostQueueMsg 

• WinQueryMsgPos 

• WinQueryQueuelnfo 

• WinQueryQueueStatus 

• WinRegisterllserDatatype 

• WinRegisterllserMsg 

• WinSendDIgltemMsg 

• WinSendMsg 

• WinSetClassMsglnterest 

• WinSetMsglnterest 

• WinSetMsgMode 

• WinSetSynchroMode 

• WinWaitMsg 
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WinQueryMsgTime  - 
Query  Message  Time 


Example  Code 

This  example  returns  position  and  time  of  the  the  last  message  obtained  from  the  current  message 
queue. 

fdefine  INCL_WINMESSAGEMGR 
fdefine  INCL_WINDIALOGS 
finclude  <0S2.H> 
finclude  <stdio.h> 

HAB  hab; 

POINTL  ptl ; 

CHAR  szMsg[100] ; 

HWND  hwnd; 

ULONG  ulTime; 


WinQueryMsgPos(hab,  &ptl ) ; 


ulTime  = WinQueryMsgTime (hab) ; 


sprintf(szMsg,  "x  = %ld  y = %ld\n\ntime  = 
ptl .x,  ptl .y,  ulTime) ; 
WinMessageBox(HWND_DESKTOP, 
hwnd, 
szMsg, 

"Debugging  information", 

0, 

MB_N0IC0N  | MB_0K) ; 


/*  client-window  handle 
/*  body  of  the  message 
/*  title  of  the  message 
/*  message  box  id 
/*  icon  and  button  flags 


*/ 

*/ 

*/ 

*/ 

*/ 
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WinQueryObjectWindow 
Query  Object  Window 


#define  INCL_WINWINDOWMGR  /*  Or  use  INCL_WIN  or  INCL_PM  V 


HWND  WinQueryObjectWindow  (HWND  hwndDeskTop) 


This  function  returns  the  desktop  object  window  handle. 

Parameters 

hwndDeskTop  (HWND)  - input 
Desktop-window  handle: 

HWND_DESKTOP  The  desktop-window  handle 
Other  Specified  desktop- window  handle. 

Returns 

Object-window  handle. 

NULLHANDLE  Error  occurred. 

Possible  returns  from  WinGetLastError 

PMERR  INVALID  HWND  An  invalid  window  handle  was  specified. 

Remarks 

Any  window  created  as  a descendant  of  hwndObject  is  an  object  window. 


Related  Functions 

• WinEnableWindow 

• WinlsThreadActive 

• WinlsWindow 

• WinlsWindowEnabled 

• WinQueryDesktopWindow 

• WinQueryWindowDC 

• WinQueryWindowProcess 

• WinQueryWindowRect 

• WinWindowFromDC 

• WinWindowFromID 

• WinWindowFromPoint 
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WinQuery  Object  Window  - 
Query  Object  Window 


Example  Code 

This  example  calls  WinQueryObjectWindow  to  return  the  desktop  object  window  handle.  All 
windows  created  as  descendants  of  this  object  window  - as  in  the  example  - will  be  object  windows. 


Idefine  INCL_WINWINDOWMGR  /*  Window  Manager  Functions  */ 

linclude  <os2.h> 

HWND  hwndObject;  /*  desktop  object  window  */ 

HWND  hwndObjectl;  /*  descendant  object  window  */ 

USHORT  Windowld; 

hwndObject  = WinQueryObjectWindow(HWND_DESKTOP) ; 

/*  create  object  window  */ 

hwndObjectl  = WinCreateWindow(hwndObject,  /*  parent  window  */ 
"NewClass",  /*  class  name  */ 

“new  button",  /*  window  text  */ 

WS_VISIBLE,  /*  window  style  */ 

0,  0,  /*  position  (x.y)  */ 

200,  100,  /*  size  (width, height)  */ 

0L,  /*  owner  window  */ 

HWND_T0P,  /*  sibling  window  */ 

Windowld,  /*  window  id  */ 

NULL,  /*  control  data  */ 

NULL);  /*  presentation  parms  */ 
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WinQueryPointer 
Query  Pointer 


#define  INCL_WINPOINTERS  /*  Or  use  INCL_WIN  or  INCL_PM  */ 


HPOINTER  WinQueryPointer  (HWND  hwndDeskTop) 


This  function  returns  the  pointer  handle  for  hwndDeskTop. 


Parameters 

hwndDeskTop  (HWND)  - input 
Desktop-window  handle: 

HWND_DESKTOP  The  desktop-window  handle 
Other  Specified  desktop-window  handle. 

Returns 

Pointer  handle. 

NULLHANDLE  Error  occurred. 

Possible  returns  from  WinGetLastError 

PMERR  INVALID  HWND  An  invalid  window  handle  was  specified. 

Related  Functions 

• WinCreatePointer 

• WinCreatePointerlndirect 

• Win  Destroy  Pointer 

• WinDrawPointer 

• WinLoadPointer 

• WinQueryPointerlnfo 

• WinQueryPointerPos 

• WinQuerySysPointer 

• WinSetPointer 

• WinSetPointerPos 

• WinShowPointer 

Example  Code 

This  example  obtains  the  pointer  handle  from  the  desktop  window  handle. 

Idefine  INCL_WINPOINTERS 
Idefine  INCL_WINDESKTOP 
linciude  <0S2.H> 

HAB  hab; 

HPOINTER  hpointer; 

hpointer  = WinQueryPointer(HWND_DESKTOP) ; 
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WinQueryPointerlnfo  - 
Query  Pointer  Information 


#define  INCL_WINPOINTERS  /*  Or  use  INCL_WIN  or  INCL_PM  */ 


BOOL  WinQueryPointerlnfo  (HPOINTER  hptr,  PPOINTERINFO  pptrlPoInterlnfo) 


This  function  returns  pointer  information. 


Parameters 

hptr  (HPOINTER)  - input 
Pointer  handle. 

pptrlPoInterlnfo  (POINTERINFO)  - output 
Pointer-information  structure. 


Returns 

Success  indicator: 

TRUE  Successful  completion 
FALSE  Error  occurred. 

Possible  returns  from  WinGetLastError 

PMERRJNVALID  HPTR  An  invalid  pointer  handle  was  specified. 

Remarks 

The  pointer  information  structure  contains  information  such  as  the  bit-map  handle  of  the  pointer  and 
action  point  coordinates.  The  values  returned  for  the  xHotspot  and  the  yHotspot  parameters  are  in 
units  relative  to  the  size  of  the  system  icon  or  system  pointer. 

For  example,  if  the  application  creates  a pointer  out  of  a bit  map  xWide  units  wide  and  positions  the 
x-coordinate  of  the  pointer’s  action  point  at  xHot,  then  this  function  will  return  the  value  of  the 
xHotspot  as: 

xHotspot  = (xHot  * SystemPointerWidth)  / xWide 

where  SystemPointerWidth  can  be  obtained  by  using  the  WinQuerySysValue  function. 


Related  Functions 

• WinCreatePointer 

• WinCreatePointerlndirect 

• WinDestroyPointer 

• WinDrawPointer 

• WinLoadPointer 

• WinQueryPointer 

• WinQueryPointerPos 

• WinQuerySysPointer 

• WinSetPointer 

• WinSetPointerPos 

• WinShowPointer 
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WinQueryPointerlnfo  - 
Query  Pointer  Information 


Example  Code 

This  example  uses  the  WinQueryPointerlnfo  call  to  obtain  the  bit-map  handle  of  the  color  bit  map. 

Idefine  INCL_WINPOINTERS 
Idefine  INCLJIINDESKTOP 
linclude  <0S2.H> 

HAB  hab; 

H POINTER  hpointer; 

POINTERINFO  pointerinfo; 

HBITMAP  hbm;  /*  Bit-map  handle  of  color  bit  map  */ 

hpointer  = WinQueryPointer(HWND_DESKTOP) ; 

Wi nQueryPoi nterlnfo (hpoi nter , 

Spointerinfo) ; 

hbm  = pointerinfo.hbmColor; 
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WinQueryPointerPos  - 
Query  Pointer  Position 


#define  INCL_WINPOINTERS  /*  Or  use  INCL_WIN  or  INCL_PM  */ 


BOOL  WinQueryPointerPos  (HWND  hwndDeskTop,  PPOINTL  pptlPolnl) 


This  function  returns  the  pointer  position. 

Parameters 

hwndDeskTop  (HWND)  - input 
Desktop-window  handle: 

HWND_DESKTOP  The  desktop-window  handle 

Other  Specified  desktop-window  handle. 

pptIPoInt  (PPOINTL)  - output 

Pointer  position  in  screen  coordinates. 


Returns 

Pointer  position  returned  indicator: 

TRUE  Successful  completion 
FALSE  Error  occurred. 

Possible  returns  from  WinGetLastError 

PMERR  INVALID  HWND  An  invalid  window  handle  was  specified. 

Remarks 

The  WinQueryMsgPos  is  used  to  get  the  pointer  position  of  the  last  message  obtained  by  means  of 
the  WinGetMsg  or  WinPeekMsg  functions. 


Related  Functions 

• WinCreatePointer 

• WinCreatePointerlndirect 

• WinDestroyPointer 

• WinDrawPointer 

• WinLoadPointer 

• WinQueryPointer 

• WinQueryPointerlnfo 

• WinQuerySysPointer 

• WinSetPointer 

• WinSetPointerPos 

• WinShowPointer 
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WinQueryPointerPos  - 
Query  Pointer  Position 


Example  Code 

This  example  displays  the  pointer  position. 


Idefine  INCL_WINWINDOWMGR 
Idefine  INCL_WINPOINTERS 
linclude  <0S2.H> 

HWND  hwndClient; 

CHAR  szMsg[100] ; 

POINTL  ptl ; 

WinQueryPointerPos(HWND_DESKTOP,  &ptl ) ; 
sprintf(szMsg,  "x  = Id  y = Id",  ptl.x,  ptl.y); 
WinMessageBox(HWND_DESKTOP, 

hwndClient,  /*  client-window  handle  */ 

szMsg,  /*  body  of  the  message  */ 

"Debugging  information",  /*  title  of  the  message  */ 

0,  /*  message  box  id  */ 

MB_N0IC0N  | MB  OK);  /*  icon  and  button  flags  */ 
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WinQueryPresParam  - 
Query  Presentation  Parameter 


#define  INCL_WINSYS  /*  Or  use  INCL_WIN  or  INCL_PM  */ 


ULONG  WinQueryPresParam  (HWND  hwnd,  ULONG  IdAttrTypel,  ULONG  ldAttrType2, 

PULONG  pldAttrT y peFound,  ULONG  cbAttrValueLen, 
PVOID  pAltrValue,  ULONG  flOptlons) 


This  function  queries  the  values  of  presentation  parameters  for  a window 


Parameters 

hwnd  (HWND)  - input 
Window  handle. 


IdAttrTypel  (ULONG)  - input 
First  attribute  type  identity. 

This  identifies  the  first  presentation  parameter  attribute  to  be  queried  It  can  be  zero  to  reference 
no  presentation  parameter  attribute. 

ldAttrType2  (ULONG)  - input 
Second  attribute  type  identity. 

This  identifies  the  second  presentation  parameter  attribute  to  be  queried.  It  can  be  zero  to 
reference  no  presentation  parameter  attribute. 

pldAttrTypeFound  (PULONG)  - input/output 
Attribute  type  identity  found. 

This  identifies  which  of  the  presentation  parameter  attributes  idAttrTypel  and  idAttrType2  has 
been  found.  This  parameter  can  be  passed  as  NULL  (if,  for  example,  only  one  attribute  is  being 
queried). 

CbAttrValueLen  (ULONG)  - input 

Byte  count  of  the  size  of  the  pAttrValue  parameter. 

pAltrValue  (PVOID)  - output 
Attribute  value. 


The  value  of  the  presentation  parameter  attribute  found. 


flOptlons  (ULONG)  - input 
Options. 

Options  controlling  the  query.  Any  of  these  can  be  ORed  together. 


QPF_NOINHERIT  For  the  purposes  of  this  query,  presentation  parameters  are  not 

inherited  from  the  owners  of  the  window  specified  by  hwnd.  If  not 
specified  (default),  presentation  parameters  are  inherited. 


QPFJD1 COLORINDEX  idAttrTypel  refers  to  a color  index  presentation  parameter  attribute, 
the  value  of  which,  if  found,  is  to  be  converted  to  RGB  before  being 
passed  back  in  pAttrValue. 

QPFJD2COLORINDEX  idAttrType2  refers  to  a color  index  presentation  parameter  attribute, 
the  value  of  which,  if  found,  is  to  be  converted  to  RGB  before  being 
passed  back  in  pAttrValue. 


QPF_PURERGBCOLOR  Specifies  that  either  or  both  of  idAttrTypel  and  idAttrType2  reference 
RGB  color,  and  that  these  colors  must  be  pure.  This  is  necessary  when 
specifying  text  foreground  and  background  colors.  This  is  applied  after 
QPFJD1  COLORINDEX  and  QPFJD2COLORINDEX. 
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WinQueryPresParam  - 
Query  Presentation  Parameter 


Returns 

Length  of  presentation  parameter  value  passed  back. 

Zero  Presentation  parameter  not  found  or  error  occurred 

Other  Length  of  presentation  parameter  value  passed  back  in  pAttrValue. 

Possible  returns  from  WinGetLastError 

PMERRINVALIDHWND  An  invalid  window  handle  was  specified. 

Remarks 

Two  presentation  parameter  attribute  identities  can  be  passed,  and  both  will  be  searched  for,  along 
the  chain  of  owners  of  the  window  hwnd  (subject  to  QPF_NOINHERIT).  The  first  one  found  satisfies 
the  query.  If  both  idAttrTypel  and  idAttrType2  are  present  for  the  same  window,  idAttrTypel  takes 
precedence. 

If  the  presentation  parameter  attribute  value  is  too  long  to  fit  in  the  pAttrValue  buffer  provided,  it  is 
truncated,  and  the  number  of  bytes  copied  is  returned  in  cbRetLen.  (See  also  WinSetPresParam  and 
WinRemovePresParam). 


Related  Functions 

• WinDrawBitmap 

• WinDrawBorder 

• WinDrawPointer 

• WinDrawText 

• WinFillRect 

• WinGetSysBitmap 

• WinlnvertRect 

• WinRemovePresParam 

• WinScrollWindow 

• WinSetPresParam 
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WinQueryPresParam  - 
Query  Presentation  Parameter 


Example  Code 

This  example  queries  the  disable-foreground  attribute;  if  it  is  a valid  attribute  of  the  window,  it  is 
removed  via  WinRemovePresParam. 

fdefine  INCL_WINSYS 
linclude  <0S2.H> 

HWND  hwnd; 

ULONG  AttrFound; 

ULONG  AttrValue[32] ; 

ULONG  cbRetLen; 


cbRetLen  = WinQueryPresParam(hwnd, 

PP_DISABLEDFOREGROUNDCOLORINDEX, 

0, 

SAttrFound, 
sizeof(AttrValue) , 

SAttrValue, 

QPF_ID1C0L0RINDEX  | QPF_N0INHERIT) ; 

if(PP_DISABLEDF0REGR0UNDC0L0RINDEX  ==  AttrFound); 

Wi nRemovePresParam( hwnd , 

PP_DISABLEDF0REGR0UNDC0L0RINDEX); 
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WinQueryQueuelnfo  - 
Query  Queue  Information 


#define  INCL_WINMESSAGEMGR  /*  Or  use  INCL_WIN  or  INCL_PM.  Also  in  COMMON  section  */ 


BOOL  WinQueryQueuelnfo  (HMQ  hmq,  PMQINFO  pmqiMqlnfo,  ULONG  cbCopled) 


This  function  returns  the  information  for  the  specified  queue. 


Parameters 

hmq  (HMQ)  - input 
Queue  handle. 

It  must  be  created  by  a previous  call  to  WinCreateMsgQueue  or  HMQCURRENT. 
pmqiMqlnfo  (PMQINFO)  - output 

Message  queue  information  structure  to  contain  the  queue  information. 
cbCopled  (ULONG)  - input 

Size  of  message  queue  information  structure  that  is  provided  (in  bytes). 

Specifies  the  maximum  number  of  bytes  to  be  copied  into  the  pmqiMqinfo  parameter.  This 
should  be  the  size  of  an  MQINFO  structure. 

Returns 

Success  indicator: 

TRUE  Successful  completion 
FALSE  Error  occurred. 

Related  Functions 

• WinBroadcastMsg 

• WinCreateMsgQueue 

• WinDestroyMsgQueue 

• WinDispatchMsg 

• WinGetDIgMsg 

• WinGetMsg 

• WinlnSendMsg 

• WinPeekMsg 

• WinPostMsg 

• WinPostQueueMsg 

• WinQueryMsgPos 

• WinQueryMsgTime 

• WinQueryQueueStatus 

• WinRegisterUserDatatype 

• WinRegisterUserMsg 

• WinSendDIgltemMsg 

• WinSendMsg 

• WinSetClassMsglnterest 

• WinSetMsglnterest 

• WinSetMsgMode 

• WinSetSynchroMode 

• WinWaitMsg 
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WinQueryQueuelnfo  - 
Query  Queue  Information 


Example  Code 

This  example  retrieves  the  process  identity  from  a queue  by  passing  the  queue  handle  to 
WinQueryQueuelnfo 

fdefine  I NCL_WI NMESSAGEMGR 
linclude  <0S2.H> 

HMQ  hmq; 

MQINFO  mqinfo; 

PID  pid; 

WinQueryQueueInfo(hmq, 

Smqinfo, 

sizeof(MQINFO)) ; 


pid  = mqinfo. pid; 
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WinQueryQueueStatus 
Query  Queue  Status 


#define  INCL_WINMESSAGEMGR  /*  Or  use  INCL_WIN  or  INCL_PM  7 


ULONG  WinQueryQueueStatus  (HWNO  hwndDeskTop) 


This  function  returns  a code  indicating  the  status  of  the  message  queue  associated  with  the  caller. 

Parameters 

hwndDeskTop  (HWND)  - input 
Desktop-window  handle: 

HWND_DESKTOP  The  desktop-window  handle 

Other  Desktop-window  handle  returned  by  WinQueryDesktopWindow. 


Returns 

Status  information. 


Summary 

Summary  of  message  types  existing  on  the  queue. 

This  field  contains  a combination  of  the  following  values: 


QS_KEY  An  input  event  (keyboard  or  journaling)  has  caused  a WMCHAR 

message  to  be  placed  in  the  queue. 

QS_MOUSE  An  input  event  has  caused  a WM_MOUSEMOVE,  WM_BUTTON1  UP, 

WM_BUTTON1  DOWN,  WM_BUTTON1  DBLCLK,  WM_BUTTON2UP, 
WM_BUTTON2DOWN,  or  WM_BUTTON2DBLCLK  message  to  be 
placed  in  the  queue. 

QS_MOUSEBUTTON  An  input  event  has  caused  a WM_BUTTON1UP,  WM_BUTTON1DOWN, 
WM_BUTTON1  DBLCLK,  WM_BUTTON2UP,  WM_BUTTON2DOWN,  or 
WMBUTTON2DBLCLK  message  to  be  placed  in  the  queue. 


QS_MOUSEMOVE 

QSTIMER 

QS_PAINT 

QSSEM1 

QSSEM2 

QSSEM3 

QSSEM4 

QSPOSTMSG 


QSSENDMSG 


An  input  event  has  caused  a WMMOUSEMOVE  message  to  be 
placed  in  the  queue. 

A timer  event  has  caused  a WMTIMER  message  to  be  placed  in  the 
queue. 

A WM_PAINT  message  is  available. 

A WM_SEM1  message  is  available. 

A WM_SEM2  message  is  available. 

A WM_SEM3  message  is  available. 

A WM  SEM4  message  is  available. 

A message  has  been  posted  to  the  queue.  Note  that  this  message  is 
probably  not  one  of  the  messages  listed  above,  but  could  be  a 
WM  CHAR,  WM_MOUSEMOVE  or  similar  message  if  an  application 
has  posted  one  of  these.  In  this  case,  the  corresponding  input  status 
flag  (QS_KEY,  QS_MOUSE,  and  so  on)  is  not  set. 

A message  has  been  sent  by  another  application  to  a window 
associated  with  the  current  queue. 
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WinQueryQueueStatus  - 
Query  Queue  Status 


Added 

Message  type  additions. 

Message  types  added  to  the  queue  since  the  last  use  of  this  function.  The  value  of  this  field 
is  a subset  of  the  Summary  field. 


Remarks 

This  function  is  an  efficient  method  for  determining  whether  input  is  available  for  processing  by  the 
WinGetMsg  or  WinPeekMsg  functions. 


Related  Functions 

• WinBroadcastMsg 

• WinCreateMsgQueue 

• WinDestroyMsgQueue 

• WinDispatchMsg 

• WinGetDIgMsg 

• WinGetMsg 

• WinlnSendMsg 

• WinPeekMsg 

• WinPostMsg 

• WinPostQueueMsg 

• WinQueryMsgPos 

• WinQueryMsgTime 

• WinQueryQueuelnfo 

• WinRegisterllserDatatype 

• WinRegisterUserMsg 

• WinSendDIgltemMsg 

• WinSendMsg 

• WinSetClassMsglnterest 

• WinSetMsglnterest 

• WinSetMsgMode 

• WinSetSynchroMode 

• WinWaitMsg 


Related  Messages 

• WM_BUTTON1UP 

• WM_BUTTON1  DOWN 

• WM_BUTTON1  DBLCLK 

• WM_BUTTON2UP 

• WM_BUTTON2DOWN 

• WM_BUTTON2DBLCLK 

• WM_CHAR 

• WM_MOUSEMOVE 

• WM_PAINT 

• WM_SEM1 

• WM_SEM2 

• WM_SEM3 

• WM_SEM4 

• WM_TIMER 
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WinQueryQueueStatus  - 
Query  Queue  Status 


Example  Code 

This  example  uses  the  WinQueryQueueStatus  to  see  if  a WM  MOUSEMOVE  message  has  been 
placed  in  the  queue. 

fdefine  INCL_WINMESSAGEMGR 
finclude  <0S2.H> 

HAB  hab; 

i f (Wi nQueryQueueStatus ( HWND_DESKTOP)  ==  QS_M0USEM0VE) 

{ 

/*  . */ 

/*  . */ 

} 
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WinQuerySessionTitle  - 
Query  Session  Title 


#define  INCL_WINSWITCHLIST  /*  Or  use  INCL_WIN  or  INCL_PM  */ 


ULONG  WinQuerySessionTitle  (HAB  hab,  ULONG  ulSesslon,  PSZ  pszTitle,  ULONG  uiTItlelen) 


This  function  obtains  the  title  under  which  a specified  application  is  started,  or  is  added  to  the 
Window  List. 

Parameters 

hab  (HAB)  - input 

Anchor-block  handle. 

ulSesslon  (ULONG)  - input 

IBM  Operating  System/2  session  identity  of  application  whose  title  is  requested: 

0 Use  the  session  identity  of  the  caller 

Other  Use  the  specified  session  identity. 

pszTitle  (PSZ)  - output 
Window  List  title. 

This  is  the  title  of  the  application  with  a process  identity,  if  the  application  is  present  in  the 
Window  List. 

uiTItlelen  (ULONG)  - input 

Maximum  length  of  data  returnable,  in  bytes. 

If  the  pszTitle  parameter  is  longer  than  this  value,  the  title  is  truncated.  However,  the 
terminating  null  character  is  left  at  the  end  of  the  string.  The  maximum  number  of  title 
characters  copied  is  (ulTitlelen—  1). 


Returns 

Return  code: 

0 Successful  completion 

Other  Error  occurred. 

Remarks 

This  function  is  useful  when  an  application  uses  the  same  name  in  its  window  title  (and  in  its  entry  in 
the  Window  List)  as  the  end  user  invokes  to  start  the  application.  This  provides  a visual  link  for  the 
end  user. 

If  this  function  is  used  after  a Window  List  entry  is  created  for  the  application,  the  title  in  the  Window 
List  entry  is  obtained.  (See  also  WinQueryTaskTitle.) 


Related  Functions 

• WinAddSwitchEntry 

• WinChangeSwitchEntry 

• WinCreateSwitchEntry 

• WinQuerySwitchEntry 

• WinQuerySwitchHandle 

• WinQuerySwitchList 

• WinQueryTaskSizePos 

• WinQueryTaskTitle 

• WinRemoveSwitchEntry 

• WinSwitchToProgram 
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WinQuerySessionTitle 
Query  Session  Title 


Example  Code 

This  example  calls  WinQuerySessionTitle  to  retrieve  the  application's  title,  and  then  sets  the  title  bar 
of  the  frame  window  to  that  title. 

fdefine  INC L_W INMESSAGEMGR 
fdefine  INCL_WINWINDOWMGR 
finclude  <0S2.H> 

HAB  hab; 

HWND  hwndFrame,  hwndClient; 

CHAR  szTitle[MAXNAMEL  + 1]; 

WinQuerySessionTitle (hab, 

0,  szTitle, 
si zeof (szT i tl e) ) ; 

hwndFrame  = WinQueryWindow(hwndClient, 

QW_PARENT);  /*  get  handle  of  parent,  */ 

/*  which  is  frame  window.  */ 

WinSetWindowText(hwndFrame,  szTitle) ; 
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WinQuerySwitchEntry  - 
Query  Switch  Entry 


#define  INCL_WINSWITCHLIST  /*  Or  use  INCL_WIN  or  INCL_PM  */ 


ULONG  WinQuerySwitchEntry  (HSWITCH  hswItchSwItch,  PSWCNTRL  pswctlSwItchData) 


This  function  obtains  a copy  of  the  Window  List  data  for  a specific  application. 

Parameters 

hswItchSwItch  (HSWITCH)  - input 
Handle  to  the  Window  List  entry. 

This  can  be  obtained  using  the  WinQuerySwitchHandle  function. 

pswctiSwitchData  (PSWCNTRL)  - output 
Switch  control  data. 

Contains  information  about  the  specified  Window  List  entry.  The  hprog  field  contains  the 
program  handle  used  to  start  the  program. 

Returns 

Return  code. 

0 Successful  completion 
Other  Error  occurred. 

Remarks 

This  function  is  available  to  PM  and  non  PM  applications. 


Related  Functions 

• WinAddSwitchEntry 

• WinChangeSwitchEntry 

• WinCreateSwitchEntry 

• WinQuerySessionTitle 

• WinQuerySwitchHandle 

• WinQuerySwitchList 

• WinQueryTaskSizePos 

• WinQueryTaskTitle 

• WinRemoveSwitchEntry 

• WinSwitchToProgram 

Example  Code 

This  example  calls  WinQuerySwitchHandle  to  get  the  Task  List  handle  of  a frame  window,  and  then 
calls  WinQuerySwitchEntry  to  retrieve  information  about  that  application. 

Idefine  INCL_WINSWITCHLIST 
linclude  <0S2.H> 

HAB  hab; 

HWND  hwnd Frame; 

HSWITCH  hswitch; 

SWCNTRL  swctl ; 

hswitch  = WinQuerySwitchHandle(hwndFrame,  0); 

WinQuerySwitchEntry(hswitch,  &swctl ) ; 
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WinQuerySwitchHandle 
Query  Switch  Handle 


#define  INCL_WINSWITCHLIST  /*  Or  use  INCL_WIN  or  INCL_PM  */ 


HSWITCH  WinQuerySwitchHandle  (HWND  hwnd,  PID  IdProcess) 


This  function  obtains  the  Window  List  handle  belonging  to  a window. 


Parameters 

hwnd  (HWND)  - input 

Window  handle  of  an  application. 

Window  handle  of  an  application  running  in  the  OS/2  session  for  which  the  Window  List  handle  is 
required. 

NULLHANDLE  Application  is  not  an  OS/2  application 

Other  Window  handle  of  an  application. 

IdProcess  (PID)  - input 

Process  identity  of  the  application. 


Returns 

Switch  list  handle  for  the  specified  application: 

NULLHANDLE  Application  is  not  in  the  switch  list,  or  an  error  occurred 
Other  Switch  list  handle. 

Remarks 

If  both  a window  handle  and  a process  identity  are  supplied,  they  must  be  consistent. 

If  the  window  handle  is  NULLHANDLE  and  the  process  identity  supplied  cannot  be  found  in  the  switch 
list  then  the  switch  handle  returned  is  the  handle  for  the  most  proximal  ancestor  process.  Once  the 
switch  list  handle  is  obtained,  it  may  be  used  in  various  other  calls  to  manipulate  the  switch  list  entry 
or  the  program  which  it  references. 


Related  Functions 

• WinAddSwitchEntry 

• WinChangeSwitchEntry 

• WinCreateSwitchEntry 

• WinQuerySessionTitle 

• WinQuerySwitchEntry 

• WinQuerySwitchList 

• WinQueryTaskSizePos 

• WinQueryTaskTitle 

• WinRemoveSwitchEntry 

• WinSwitchToProgram 
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WinQuerySwitchHandle  - 
Query  Switch  Handle 


Example  Code 

This  example  calls  WinQuerySwitchHandle  to  get  the  Task  List  handle  of  a frame  window,  and  then 
calls  WinQuerySwitchEntry  to  retrieve  information  about  that  application. 

fdefine  INCL_WINSWITCHLIST 
linclude  <0S2.H> 

HAB  hab; 

HWND  hwndFrame; 

HSWITCH  hswitch; 

SWCNTRL  swctl ; 

hswitch  = WinQuerySwitchHandle(hwndFrame,  0); 

WinQuerySwitchEntry(hswitch,  &swctl ) ; 
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WinQuerySwitchList 
Query  Switch  List 


#define  INCL_WINSWITCHLIST  /*  Or  use  INCL_WIN  or  INCL_PM  7 


ULONG  WinQuerySwitchList  (HAB  hab,  PSWBLOCK  pswblkBiock,  ULONG  ulLength) 


This  function  obtains  information  about  the  entries  in  the  Window  List. 

Parameters 

hab  (HAB)  - input 

Anchor-block  handle. 

pswblkBiock  (PSWBLOCK)  - input/output 
Switch  entries  block. 

Contains  a description  of  all  the  entries  in  the  current  switch  list.  This  is  held  in  a SWBLOCK 
structure,  which  has  a count  of  the  number  of  switch  list  entries,  plus  a record  for  each  entry 
containing  data  such  as  the  process  and  session  identities,  the  icon  handle,  and  the  window 
handle  for  the  running  program. 

NULL  No  information  returned;  the  return  parameter  however  contains  the  total  number  of 
switch  list  entries. 

Other  Switch  entries  block. 

ulLength  (ULONG)  - input 

Maximum  length  of  data  returnable  in  bytes. 

This  is  the  maximum  length  in  bytes  of  the  data  that  can  be  returned  in  the  pswblkBiock 
parameter. 

0 No  information  returned,  however  the  return  parameter  contains  the  total  number  of 

switch  list  entries. 

Other  Maximum  length  of  data  returnable. 

Returns 

Total  number  of  switch  list  entries  present  in  the  system. 

0 Error  occurred 

Other  Total  number  of  switch  list  entries  present  in  the  system. 

Remarks 

It  is  possible  to  obtain  information  about  all  the  programs  currently  executing  in  a single  operation, 
with  one  array  entry  for  each  program. 


Related  Functions 

• WinAddSwitchEntry 

• WinChangeSwitchEntry 

• WinCreateSwitchEntry 

• WinQuerySessionTitle 

• WinQuerySwitchEntry 

• WinQuerySwitchHandle 

• WinQueryTaskSizePos 

• WinQueryTaskTitle 

• WinRemoveSwitchEntry 

• WinSwitchToProgram 
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Win  Query  Switch  List  - 
Query  Switch  List 


Example  Code 

This  example  calls  WinQuerySwitchList  to  determine  the  number  of  items  in  the  Task  List,  allocates 
memory  for  the  required  buffer,  and  calls  WinQuerySwitchList  again  to  fill  the  buffer  with  the 
information  about  each  program  in  the  Task  List. 

fdefine  INCL_DOSMEMMGR 
Idefine  INCL_WINSWITCHLIST 
finclude  <0S2.H> 

HAB  hab; 

HWND  hwndFrame; 

ULONG  cbl terns,  cbBuf; 

ULONG  pBase; 

PSWBLOCK  pswblk; 

SEL  sel ; 

Dos A1 1 ocMem ( ( PPVOID) pBase, 

(ULONG) 40000, 

PAG_READ  | 

PAG_WRITE) ; 


/*  . */ 


cbltems  = WinQuerySwitchList (hab,  NULL,  0);  /*  gets  num.  of  items  */ 

cbBuf  = (cbltems  * sizeof(SWENTRY))  + sizeof(HSWITCH); 

DosSubAl 1 ocMem ( ( PVOI D) pBas  e , 

(PPVOID)pswblk, 

(ULONG)  cbBuf); 

WinQuerySwitchList(hab,  pswblk,  cbBuf);  /*  gets  struct,  array  */ 
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WinQuerySysColor 
Query  System  Color 


#define  INCL_WINSYS  /*  Or  use  INCL_WIN  or  INCL_PM  */ 


LONG  WinQuerySysColor  (HWND  hwndDeskTop,  LONG  IColor,  LONG  IReserved) 


This  function  returns  the  system  color. 

Parameters 

hwndDeskTop  (HWND)  - input 
Desktop-window  handle: 

HWND_DESKTOP  The  desktop-window  handle 

Other  Specified  desktop-window  handle. 

IColor  (LONG)  - input 

System  color-index  value. 

Must  be  one  of  the  SYSCLR_*  index  values  defined  under  the  WinSetSysColors  function. 

IReserved  (LONG)  - input 
Reserved. 

0 Reserved  value;  must  be  0. 

Returns 

RGB  value. 

RGB  value  corresponding  to  the  IColor  parameter. 

Possible  returns  from  WinGetLastError 

PMERR  INVALID  HWND  An  invalid  window  handle  was  specified. 

PMERR_PARAMETER_OUT_OF_RANGE  The  value  of  a parameter  was  not  within  the  defined  valid 

range  for  that  parameter. 

Remarks 

This  function  returns  the  color  value  that  corresponds  to  the  specified  color  index  of  the  specified 
color  palette. 

Related  Functions 

• WinSetSysColors 
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WinQuerySysColor  - 
Query  System  Color 


Example  Code 

This  example  uses  the  WinQuerySysColor  to  find  the  RGB  index  of  the  system  pushbutton, 
SYSCLR_BUTTONDEFAULT 

Idefine  INCL_WINSYS 
fdefine  INCL_WINDESKTOP 
finclude  <0S2.H> 

HAB  hab; 

LONG  1 RgbColor; 


lRgbColor  = WinQuerySysColor(HWND_DESKTOP, 

SYSCLRBUTTONDEFAULT, 

0L); 
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WinQuerySysModal Window  - 
Query  System  Modal  Window 


#define  INCL_WINWINDOWMGR  /*  Or  use  INCL_WIN  or  INCL_PM  7 


HWNO  WinQuerySysModalWindow  (HWND  hwndDeskTop) 


This  function  returns  the  current  system  modal  window. 

Parameters 

hwndDeskTop  (HWND)  - input 
Desktop-window  handle: 

HWND_DESKTOP  The  desktop-window  handle 
Other  Specified  desktop-window  handle. 

Returns 

Handle  of  system  modal  window: 

NULLHANDLE  No  system  modal  window 
Other  Handle  of  system  modal  window. 

Possible  returns  from  WinGetLastError 

PMERR  INVALID  HWND  An  invalid  window  handle  was  specified. 

Remarks 

For  a full  description  of  the  operation  of  the  system  modal  window,  see  the  WinSetSysModalWindow 
function. 

Related  Functions 

• WinSetSysModalWindow 


Example  Code 

This  example  uses  the  WinQuerySysModalWindow  to  find  the  handle  of  the  system  modal  window. 

Idefine  INCL_WINWINDOWMGR 
linclude  <0S2.H> 

HAB  hab; 

HWND  hwndDeskTop,  hwndSysModal ; 

LONG  lRgbColor; 

/*  Input  processing  can  enter  a "system  modal"  state.  In  */ 

/*  this  state,  all  pointing  device  and  keyboard  input  */ 

/*  is  directed  to  a special  window,  known  as  the  */ 

/*  system-modal  window.  Typically,  this  will  be  a dialog  */ 

/*  window  requiring  input.  */ 

hwndSysModal  = WinQuerySysModalWindow(hwndDeskTop) ; 
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WinQuerySysPointer  - 
Query  System  Pointer 


#define  INCL_WINPOINTERS  /*  Or  use  INCL_WIN  or  INCL_PM  7 


HPOINTER  WinQuerySysPointer  (HWND  hwndDeskTop,  LONG  (Identifier,  BOOL  fCopy) 


This  function  returns  the  system-pointer  handle. 


Parameters 

hwndDeskTop  (HWND)  - input 
Desktop- window  handle. 

(Identifier  (LONG)  - input 
System-pointer  identifier: 


SPTR_ARROW 

SPTR_TEXT 

SPTR_WAIT 

SPTR_SIZE 

SPTR_MOVE 

SPTRSIZENWSE 

SPTRSIZENESW 

SPTRSIZEWE 

SPTRSIZENS 

SPTR_APPICON 

SPTRJCONINFORMATION 

SPTRICONQUESICON 

SPTRICONERROR 

SPTRICONWARNING 

SPTRILLEGAL 

SPTR_FILE 

SPTR_MULTFILE 

SPTR_FOLDER 

SPTRPROGRAM 


Arrow  pointer 
Text  I-beam  pointer 
Hourglass  pointer 
Size  pointer 
Move  pointer 

Downward-sloping,  double-headed  arrow  pointer 

Upward-sloping,  double-headed  arrow  pointer 

Horizontal,  double-headed  arrow  pointer 

Vertical,  double-headed  arrow  pointer 

Standard  application  icon  pointer 

Information  icon  pointer 

Question  mark  icon  pointer 

Exclamation  mark  icon  pointer 

Warning  icon  pointer 

Illegal  operation  icon  pointer 

Single  file  icon  pointer 

Multiple  files  icon  pointer 

Folder  icon  pointer 

Application  program  icon  pointer 


(Copy  (BOOL)  - input 
Copy  indicator: 

TRUE  Create  a copy  of  the  system  pointer  and  return  its  handle.  Specify  this  value  if  the 
system  pointer  is  to  be  modified. 

FALSE  Return  the  handle  of  the  system  pointer. 
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WinQuerySysPointer 
Query  System  Pointer 


Returns 

Pointer  handle. 

Possible  returns  from  WinGetLastError 

PMERR  INVALID  HWND  An  invalid  window  handle  was  specified. 

PMERR_PARAMETER_OUT_OF_RANGE  The  value  of  a parameter  was  not  within  the  defined  valid 

range  for  that  parameter. 

Remarks 

Take  care  when  using  the  pointer  bit-map  handles  returned  by  the  WinQueryPointerlnfo  function  in 
the  POINTERINFO  structure.  If  the  handle  is  a system-pointer  handle,  or  is  returned  by  the 
WinQueryPointerlnfo  function,  it  is  possible  that  another  application  is  also  accessing  the  bit-map 
handle.  If  this  is  so,  selecting  the  bit  map  into  a presentation  space  may  fail.  Only  the  active  thread 
may  use  the  bit-map  handle  returned  by  either  the  WinQuerySysPointer  function,  when  fCopy  is 
FALSE,  or  by  the  WinQueryPointerlnfo  function. 

Note:  This  rule  is  not  enforced  by  the  system;  therefore,  ensure  that  the  program  handles  selection 
failures  correctly. 


Related  Functions 

• WinCreatePointer 

• WinCreatePointerlndirect 

• WinDestroyPointer 

• WinDrawPointer 

• WinLoadPointer 

• WinQueryPointer 

• WinQueryPointerlnfo 

• WinQueryPointerPos 

• WinSetPointer 

• WinSetPointerPos 

• WinShowPointer 
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WinQuerySysPointer  - 
Query  System  Pointer 


Example  Code 

This  example  calls  WinQuerySysPointer  to  get  a handle  to  the  system  pointer,  and  then  loads  an 
application-defined  pointer.  After  it  has  finished  using  the  application-defined  pointer,  it  restores  the 
system  pointer. 

fdefine  INCL_WINPOINTERS 
finclude  <0S2.H> 
fdefine  IDP_CROSSHAIR  900 
HWND  hptrDefault,  hptrCrossHair; 

/*  get  the  system  pointer  */ 

hptrDefault  = WinQuerySysPointer(HWND_DESKTOP,  SPTR_ARROW,  FALSE); 

/*  load  an  application-defined  pointer  */ 

hptrCrossHair  = WinLoadPointer(HWND_DESKTOP,  (ULONG)O,  IDP_CROSSHAIR) ; 

/*  change  the  pointer  to  the  application  pointer  */ 

WinSetPointer(HWND_DESKTOP,  hptrCrossHair); 

/*  restore  the  system  pointer  */ 

WinSetPointer(HWND_DESKTOP,  hptrDefault); 
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WinQuerySysValue 
Query  System  Value 


#define  INCL_WINSYS  /*  Or  use  INCL_WIN  or  INCL_PM  */ 


LONG  WinQuerySysValue  (HWND  hwndDeskTop,  LONG  IValueld) 


This  function  returns  a system  value. 

Parameters 

hwndDeskTop  (HWNO)  - input 
Desktop-window  handle: 

HWND_DESKTOP  Return  the  system  values  for  the  desktop-window  handle 

Other  Return  the  system  values  for  the  specified  desktop-window  handle. 

IVaiueid  (LONG)  - input 
System-value  identity. 

This  must  be  one  of  the  following  SV_*  constants. 

Note:  Not  all  system  values  can  be  set  with  the  WinSetSysValue  function;  those  that  can  be  set 
are  marked  with  an  asterisk  (*). 


SV_CXSCREEN 

Width  of  the  screen. 

SVCYSCREEN 

Height  of  the  screen. 

SVCXVSCROLL 

Width  of  the  vertical  scroll-bar. 

SVCYHSCROLL 

Height  of  the  horizontal  scroll-bar. 

SVCYVSCROLLARROW 

Height  of  the  vertical  scroll-bar  arrow  bit  maps. 

SVCXHSCROLLARROW 

Width  of  the  horizontal  scroll-bar  arrow  bit  maps. 

SV_CYTITLEBAR 

Height  of  the  caption. 

SVCXBORDER 

Width  of  the  nominal-width  border. 

SVCYBORDER 

Height  of  the  nominal-width  border. 

SVCXSIZEBORDER 

(<*)  Width  of  the  sizing  border. 

SVCYSIZEBORDER 

(*)  Height  of  the  sizing  border. 

SVCXDLGFR  AM  E 

Width  of  the  dialog-frame  border. 

SVCYDLGFRAME 

Height  of  the  dialog-frame  border. 

SVCYVSLIDER 

Height  of  the  vertical  scroll-bar  thumb. 

SVCXHSLIDER 

Width  of  the  horizontal  scroll-bar  thumb. 

SVCXMINMAXBUTTON 

Width  of  the  minimize/maximize  buttons. 

SVCYMINMAXBUTTON 

Height  of  the  minimize/maximize  buttons. 

SVCYMENU 

Height  of  the  single-line  menu  height. 

SVCXFULLSCREEN 

Width  of  the  client  area  when  the  window  is  full  screen. 

SVCYFULLSCREEN 

Height  of  the  client  area  when  the  window  is  full  screen 
(excluding  menu  height). 

SVCXICON 

Icon  width. 

SV_CYICON 

Icon  height. 

SV_CXPOINTER 

Pointer  width. 
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WinQuerySysValue  - 
Query  System  Value 


SV_CYPOINTER  Pointer  height. 


SV_DEBUG 

SVCMOUSEBUTTONS 

SVPOINTERLEVEL 


SVCTIMERS 

SV_SWAPBUTTON 


SVCURSORRATE 

SVDBLCLKTIME 

SVCXDBLCLK 

SVCYDBLCLK 

SVALARM 

SVWARNINGFREQ 

SVWARNINGDURATION 

SVNOTEFREQ 

SVNOTEDURATION 

SVERRORFREQ 

SVERRORDURATION 

SVFIRSTSCROLLRATE 

SVSCROLLRATE 

SVCURSORLEVEL 

SVTRACKRECTLEVEL 

SVCXBYTEALIGN 

SVCYBYTEALIGN 

SVSETLIGHTS 


FALSE  indicates  this  is  not  a debug  system. 

The  number  of  buttons  on  the  pointing  device  (zero  if  no 
pointing  device  is  installed). 

Pointer  hide  level.  If  the  pointer  level  is  zero,  the  pointer  is 
visible.  If  it  is  greater  than  zero,  the  pointer  is  not  visible.  The 
WinShowPointer  call  is  invoked  to  increment  and  decrement  the 
SV_POINTERLEVEL,  but  its  value  cannot  become  negative. 

Count  of  available  timers. 

(*)  TRUE  if  pointing  device  buttons  are  swapped.  Normally,  the 
pointing  device  buttons  are  set  for  right-handed  use.  Setting  this 
value  changes  them  for  left-handed  use. 

If  TRUE,  WM  LBUTTON*  messages  are  returned  when  the  user 
presses  the  right  button,  and  WM  RBUTTON*  messages  are 
returned  when  the  left  button  is  pressed.  Modifying  this  value 
affects  the  entire  system.  Applications  should  not  normally  read 
or  set  this  value;  users  update  this  value  by  means  of  the  user 
interface  shell  to  suit  their  requirements. 

(*)  Cursor  blink  rate,  in  milliseconds. 

(*)  Pointing  device  double-click  time,  in  milliseconds. 

(*)  Width  of  the  pointing  device  double-click  sensitive  area.  The 
default  is  the  system-font  character  width. 

(*)  Height  of  the  pointing  device  double-click  sensitive  area.  The 
default  is  half  the  height  of  the  system  font  character  height. 

(*)  TRUE  if  the  alarm  sound  generated  by  WinAlarm  is  enabled; 
FALSE  if  the  alarm  sound  is  disabled. 

(*)  Frequency  for  warning  alarms  generated  by  WinAlarm. 

(*)  Duration  for  warning  alarms  generated  by  WinAlarm. 

(*)  Frequency  for  note  alarms  generated  by  WinAlarm. 

(*)  Duration  for  note  alarms  generated  by  WinAlarm. 

(*)  Frequency  for  error  alarms  generated  by  WinAlarm. 

(*)  Duration  for  error  alarms  generated  by  WinAlarm. 

(*)  The  delay  (in  milliseconds)  before  autoscrolling  starts,  when 
using  a scroll  bar. 

(*)  The  delay  (in  milliseconds)  between  scroll  operations,  when 
using  a scroll  bar. 

The  cursor  hide  level. 

The  hide  level  of  the  tracking  rectangle  (zero  if  visible,  greater 
than  zero  if  not). 

Horizontal  count  of  pels  for  alignment. 

Vertical  count  of  pels  for  alignment. 

(*)  When  TRUE,  the  appropriate  light  is  set  when  the  keyboard 
state  table  is  set. 
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SV_INSERTMODE 

SVMENUROLLDOWNDELAY 

SVMENUROLLUPDELAY 

SVMOUSEPRESENT 

SVMONOICONS 

SVKBDALTERED 


SVPRINTSCREEN 

SVBEGINDRAG 

SVENDDRAG 

SVBEGINSELECT 

SVENDSELECT 

SV_OPEN 

SVCONTEXTMENU 

SV_TEXTEDIT 

SVCONTEXTMENUKB 

SV_TEXTEDITKB 


(*)  TRUE  if  the  system  is  in  insert  mode  (for  edit  and  multi-line 
edit  controls);  FALSE  if  in  overtype  mode. 

This  system  value  is  toggled  by  the  system  when  the  insert  key 
is  toggled,  regardless  of  which  window  has  the  focus  at  the  time. 

(*)  The  delay  in  milliseconds  before  displaying  a pull  down 
referred  to  from  a submenu  item,  when  the  button  is  already 
down  as  the  pointer  moves  onto  the  submenu  item. 

(*)  The  delay  in  milliseconds  before  hiding  a pull  down  referred 
to  from  a submenu  item,  when  the  button  is  already  down  as  the 
pointer  moves  off  the  submenu  item. 

When  TRUE  a mouse  pointing  device  is  attached  to  the  system. 

When  TRUE  preference  is  given  to  black  and  white  icons  when 
selecting  which  icon  resource  definition  to  use  on  the  screen. 
Black  and  white  icons  may  have  more  clarity  than  color  icons  on 
LCD  and  Plasma  display  screens. 

Hardware  ID  of  the  newly  attached  keyboard. 

Note:  The  OS/2  National  Language  Support  is  only  loaded  once 
per  system  IPL.  The  OS/2  NLS  translation  is  based  partially  on 
the  type  of  keyboard  device  attached  to  the  system.  There  are 
two  main  keyboard  device  types:  PC  AT  styled  and  Enhanced 
styled.  Hot  Plugging  between  these  two  types  of  devices  may 
result  in  typing  anomalies  due  to  a mismatch  in  the  NLS  device 
tables  loaded  and  that  of  the  attached  device.  It  is  strongly 
recommended  that  keyboard  hot  plugging  be  limited  to  the 
device  type  that  the  system  was  IPL'd  with.  In  addition,  OS/2 
support  will  default  to  the  101/102  key  Enhanced  keyboard  if  no 
keyboard  or  a NetServer  Mode  password  was  in  use  during 
system  IPL.  (See  Category  4,  lOCtls  77h  and  7Ah  for  more 
information  on  keyboard  devices  and  types.) 

(*)  TRUE  when  the  Print  Screen  function  is  enabled;  FALSE  when 
the  Print  Screen  function  is  disabled. 

Mouse  begin  drag  (low  word=mouse  message  id  (WM_*),  high 
word=keyboard  control  code  (KC_*)) 

Mouse  end  drag  (low  word=mouse  message  id  (WM_*),  high 
word=keyboard  control  code  (KC_*)) 

Mouse  begin  swipe  select  (low  word=mouse  message  id 
(WM_*),  high  word=keyboard  control  code  (KC_*)) 

Mouse  select  or  end  swipe  select  (low  word=mouse  message  id 
(WM_*),  high  word=keyboard  control  code  (KC_*)) 

Mouse  open  (low  word=mouse  message  id  (WM_*),  high 
word=keyboard  control  code  (KC_*)) 

Mouse  request  popup  menu  (low  word=mouse  message  id 
(WM_*),  high  word=keyboard  control  code  (KC_*)) 

Mouse  begin  direct  name  edit  (low  word=mouse  message  id 
(WM_*),  high  word=keyboard  control  code  (KC_*)) 

Keyboard  request  popup  menu  (low  word=virtual  key  code 
(VK_*),  high  word=keyboard  control  code  (KC_*)) 

Keyboard  begin  direct  name  edit  (low  word=virtual  key  code 
(VK_*),  high  word=keyboard  control  code  (KC_*)) 
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Returns 

System  value: 

0 Error  occurred 

Other  System  value.  Dimensions  are  in  pels  and  times  are  in  milliseconds. 

Possible  returns  from  WinGetLastError 

PMERRJNVALIDHWND 
PMERRPARAMETEROUTOFRANGE 

Related  Functions 

• WinSetSysValue 

Example  Code 

This  example  uses  the  WinQuerySysValue  function  to  query  the  sizing  border  dimensions. 

Idefine  INCL_WINSYS 
finclude  <0S2.H> 

LONG  vlXBorder,  vlYBorder; 

vlXBorder  = WinQuerySysValue(HWND_DESKTOP, 

SV_CXSIZEBORDER) ; 

vlYBorder  = WinQuerySysValue(HWND_DESKTOP, 

SV_CYSIZEBORDER) ; 


An  invalid  window  handle  was  specified. 

The  value  of  a parameter  was  not  within  the  defined  valid 
range  for  that  parameter. 
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Query  System  Atom  Table 


#define  INCL_WINATOM  /*  Or  use  INCL_WIN  or  INCL_PM  */ 


HATOMTBL  WinQuerySystemAtomTable  () 


This  function  returns  the  handle  of  the  system  atom  table. 


Parameters 

Returns 

System  atom-table  handle. 


Remarks 

The  system  atom  table  can  be  accessed  by  any  process  in  the  system.  It  is  created  at  boot  time  and 
cannot  be  destroyed. 


Related  Functions 

• WinAddAtom 

• WinCreateAtomTable 

• WinDeleteAtom 

• WinDestroyAtomTable 

• WinFindAtom 

• WinQueryAtomLength 

• WinQueryAtomName 

• WinQueryAtomllsage 

Example  Code 

This  function  queries  the  length  of  an  atom. 

fdefine  INCL_WINATOM 
finclude  <0S2.H> 

HATOMTBL  hatomtbl ; 

ATOM  atom; 

unsigned  char  szAtomName; 

hatomtbl  = WinQuerySystemAtomTableO ; 


atom  = WinFindAtom(hatomtbl , &szAtomName) ; 
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#define  INCL_WINSWITCHLIST  /*  Or  use  INCL_WIN  or  INCL_PM  */ 


ULONG  WinQueryTaskSizePos  (HAB  hab,  ULONG  utID,  PSWP  pswp) 


This  function  obtains  the  recommended  size,  position  and  status  for  the  first  window  of  a newly 
started  application  (typically  the  main  window). 


Parameters 

hab  (HAB)  - input 

Anchor-block  handle. 

uilD  (ULONG)  - input 
Session. 

If  zero  is  specified,  the  session  number  of  the  caller  is  used. 

pswp  (PSWP)  - output 

Window  position  and  size  data. 

Contains  the  recommended  size  and  position  for  the  first  (main)  window  of  the  application.  The 
window  flags  are  set  to  indicate  whether  this  window  should  be  activated,  minimized,  or 
maximized. 

Returns 

Return  code: 

0 Successful  completion 
Other  Error  occurred. 

Remarks 

The  recommended  size,  position,  and  status  for  the  program  which  is  starting  up,  may  be  contained 
in  the  initialization  file.  However,  if  no  data  is  available  in  the  initialization  file,  the  system  generates 
values. 

The  coordinates  returned  are  screen  coordinates. 

Note:  For  a standard  window,  the  values  returned  apply  to  the  frame  window,  not  the  client  window. 
Where  generated  values  are  supplied,  they  are  such  as  to  guarantee  a non  null  client  window  area 
within  a FS_STANDARD  frame  window. 

Related  Functions 

• WinAddSwitchEntry 

• WinChangeSwitchEntry 

• WinCreateSwitchEntry 

• WinQuerySessionTitle 

• WinQuerySwitchEntry 

• WinQuerySwitchHandle 

• WinQuerySwitchList 

• WinQueryTaskTitle 

• WinRemoveSwitchEntry 

• WinSwitchToProgram 
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WinQueryTaskSizePos  - 

Query  Task  Window  Size  and  Position 


Example  Code 

This  example  uses  the  recommended  size,  position  and  status  from  the  WinQueryTaskSize  function 
to  position  the  first  window  of  a newly-started  application  (typically  the  main  window). 

fdefine  INCL_WINSWITCHLIST 
fdefine  INCL_WINFRAMEMGR 
finclude  <0S2.H> 

HAB  hab; 

SWP  winpos; 

HWND  hwndFrame; 


WinQueryTaskSizePos (hab, 


0, 

&winpos) ; 


Wi  nSetWi ndowPos ( hwndFrame , 
winpos. x, 
winpos. y, 
winpos. cx, 
wi  npos.cy, 

SWP_ACTIVATE  | SWP_M0VE 


HWND_T0P , 

/*  x pos  */ 
/*  y pos  */ 
/*  x size  */ 
/*  y size  */ 

| SWP_SIZE  | SWP_SH0W) ; /*  flags*/ 
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Query  Task  Title 


#define  INCL_WINSWITCHLIST  /*  Or  use  INCL_WIN  or  INCL_PM  */ 


ULONG  WinQueryTaskTitle  (ULONG  ulSession,  PSZ  pszTitle,  ULONG  ulTItlelen) 


This  function  obtains  the  title  under  which  a specified  application  is  started,  or  is  added  to  the 
Window  List.  (See  also  WinQuerySessionTitle,  which  you  should  use  for  preference.) 


Parameters 

ulSession  (ULONG)  - input 

Session  identity  of  application  whose  title  is  requested: 

0 Use  the  session  identity  of  the  caller 

Other  Use  the  specified  session  identity. 

pszTitle  (PSZ)  - output 
Window  List  title. 

This  is  the  title  of  the  application  with  a process  identity,  if  the  application  is  present  in  the 
Window  List. 

ulTItlelen  (ULONG)  - input 

Maximum  length  of  data  returnable,  in  bytes. 

If  the  pszTitle  parameter  is  longer  than  this,  the  title  is  truncated.  However,  the  terminating  null 
character  is  left  atthe  end  of  the  string.  The  maximum  number  of  title  characters  copied  is 
(ulTitlelen— 1). 


Returns 

Return  code: 

0 Successful  completion 
Other  Error  occurred. 

Remarks 

This  function  is  useful  when  an  application  uses  the  same  name  in  its  window  title  (and  in  its  entry  in 
the  Window  List)  as  the  end  user  invokes  to  start  the  application.  This  provides  a visual  link  for  the 
end  user. 

If  this  function  is  used  after  a Window  List  entry  is  created  for  the  application,  the  title  in  the  Window 
List  entry  is  obtained. 


Related  Functions 

• WinAddSwitchEntry 

• WinChangeSwitchEntry 

• WinCreateSwitchEntry 

• WinQuerySessionTitle 

• WinQuerySwitchEntry 

• WinQuerySwitchHandle 

• WinQuerySwitchList 

• WinQueryTaskSizePos 

• WinRemoveSwitchEntry 

• WinSwitchToProgram 
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WinQueryT  askTitle 
Query  Task  Title 


Example  Code 

This  example  calls  WinQueryTaskTitle  to  retrieve  the  application's  title,  and  then  sets  the  title  bar  of 
the  frame  window  to  that  title.  (The  WinQuerySessionTitle  could  be  used  instead). 

fdefine  INCL_WINSWITCHLIST 
linclude  <0S2.H> 

HAB  hab; 

HWND  hwndFrame,  hwndClient; 

CHAR  szTitle[MAXNAMEL  + 1]; 

HSWITCH  hswitch; 

SWCNTRL  swctl ; 

hswitch  = WinQuerySwitchHandle(hwndFrame,  0); 

WinQuerySwitchEntry(hswitch,  Sswctl ) ; 

WinQueryTaskTitle(0, 

szTitle, 

sizeof(szTitle)) ; 

hwndFrame  = WinQueryWindow(hwndClient, 

QW_PARENT);  /*  get  handle  of  parent,  */ 

/*  which  is  frame  window.  */ 

WinSetWindowText(hwndFrame,  szTitle) ; 
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Query  Update  Rectangle 


#define  INCL_WINWINDOWMGR  /*  Or  use  INCL_WIN  or  INCL_PM  */ 


BOOL  WlnQueryUpdateRect  (HWND  hwnd,  PRECTL  prcIPrc) 


This  function  returns  the  rectangle  that  bounds  the  update  region  of  a specified  window. 

Parameters 

hwnd  (HWND)  - input 

Handle  of  window  whose  update  rectangle  is  to  be  queried. 
prcIPrc  (PRECTL)  - output 

Update  region  that  bounds  the  rectangle  (in  window  coordinates). 

Note:  The  value  of  each  field  in  this  structure  must  be  in  the  range  —32  768  through  32  767.  The 
datatype  WRECT  may  also  be  used,  if  supported  by  the  language. 

Returns 

Success  indicator: 

TRUE  Successful  completion 

FALSE  Window  has  no  update  region;  it  is  wholly  valid,  therefore  prcIPrc  is  NULL. 

Possible  returns  from  WinGetLastError 

PMERRINVALIDHWND  An  invalid  window  handle  was  specified. 

Remarks 

This  function  is  useful  for  implementing  an  incremental  update  scheme  as  an  alternative  to  the 
WinBeginPaint  and  WinEndPaint  functions. 


Related  Functions 

• WinBeginPaint 

• WinEnableWindowUpdate 

• WinEndPaint 

• WinExcludeUpdateRegion 

• WinGetClipPS 

• WinGetPS 

• WinGetScreenPS 

• WinlnvalidateRect 

• WinlnvalidateRegion 

• WinlsWindowShowIng 

• WinlsWindowVisible 

• WinLockVisRegions 

• WinOpenWindowDC 

• WinQueryUpdateRegion 

• WinRealizePalette 

• WinReleasePS 

• WinShowWindow 

• WinUpdateWindow 

• WinValidateRect 

• WinValidateRegion 
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Query  Update  Rectangle 


Example  Code 

This  example  gets  the  dimensions  of  the  window  and  calls  WinlnvalidateRect  to  invalidate  the 
window.  The  application  will  be  sent  a WMPAINT  message  with  the  entire  window  as  the  update 
rectangle. 

fdefine  INCL_WINWINDOWMGR 
finclude  <0S2.H> 

HAB  hab; 

HWND  hwnd; 

RECTL  rcl ; 


WinQueryWindowRect(hwnd,  &rcl 
WinInvalidateRect(hwnd,  /* 
&rcl , /* 

FALSE) ; /* 


); 

window  to  invalidate  */ 
invalid  rectangle  */ 
do  not  include  children  */ 
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Query  Update  Region 


#define  INCL_WINWINDOWMGR  /*  Or  use  INCL_WIN  or  INCL_PM  */ 


LONG  WinQueryUpdateRegion  (HWNO  hwnd,  HRGN  hrgn) 


This  call  obtains  an  update  region  of  a window. 

Parameters 

hwnd  (HWND)  - input 

Handle  of  window  whose  update  region  is  to  be  queried. 

hrgn  (HRGN)  - input 

Handle  of  the  window’s  update  region. 

The  window’s  update  region,  in  window  coordinates,  is  copied  into  hrgn. 

Returns 

Complexity  of  resulting  region/error  indicator: 

RGN_NULL  Null  region 

RGN_RECT  Rectangular  region 

RGN_COMPLEX  Complex  region 
RGN  ERROR  Error. 


Possible  returns  from  WinGetLastError 

PMERRINVALIDHWND 
PMERR  HRGN  BUSY 


An  invalid  window  handle  was  specified. 

An  internal  region  busy  error  was  detected.  The  region 
was  locked  by  one  thread  during  an  attempt  to  access  it 
from  another  thread. 


Remarks 

This  call  is  useful  for  implementing  an  alternate  update  scheme  to  those  used  by  the  WinBeginPaint, 
and  WinEndPaint  functions,  together  with  the  WinValidateRegion  function. 

The  application  can  use  the  returned  update  region  as  the  clip  region  for  a presentation  space,  so 
that  drawing  output  can  be  clipped  to  the  window’s  update  region. 
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Query  Update  Region 


Related  Functions 

• WinBeginPaint 

• WinEnableWindowllpdate 

• WinEndPaint 

• WinExcludellpdateRegion 

• WinGetClipPS 

• WinGetPS 

• WinGetScreenPS 

• WinlnvalidateRect 

• WinlnvalidateRegion 

• WinlsWindowShowing 

• WinlsWindowVisible 

• WinLockVisRegions 

• WinOpenWindowDC 

• WinQueryllpdateRect 

• WinRealizePalette 

• WinReleasePS 

• WinShowWindow 

• WinUpdateWindow 

• WinValidateRect 

• WinValidateRegion 

Example  Code 

This  example  gets  the  region  that  needs  to  be  updated  and  then  repaints  the  invalid  region,  if 
necessary. 

fdefine  INCLJIINWINDOWMGR 
fdefine  INCL_GPIREGIONS 
finclude  <0S2.H> 

HWND  hwnd; 

HRGN  hrgn;  /*  region  handle.  */ 

if  (RGN_NULL  !=  WinQueryUpdateRegion (hwnd,  hrgn))  { 

/*  repaint  the  invalid  region  */ 


} 
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Query  Version 


#define  INCL_WINWINDOWMGR  /*  Or  use  INCL_WIN  or  INCL_PM.  Also  in  COMMON  section  7 


ULONG  WinQueryVersion  (HAB  hab) 


This  function  returns  the  version,  the  revision  level  and  the  environment  of  PM. 

Parameters 

hab  (HAB)  - input 

Anchor-block  handle. 


Returns 

System  information  within  which  the  application  is  operating: 

SYSINF_ENV 

Environment: 

QV_OS2  OS/2. 

SYSINF_MAJVER 

Major  version  number  of  PM. 

10  OS/2  Presentation  Manager  Version  1. 

SYSINFM  INVER 

Minor  version  (revision)  number  of  PM. 

10  Revision  1 
20  Revision  2. 

Example  Code 

This  example  gets  the  version  of  PM  that  is  running. 

Idefine  INCL_GPIREGIONS 
finclude  <0S2.H> 
linclude  <stdio.h> 

HAB  hab; 

ULONG  1 Ver; 

IVer  = WinQueryVersion(hab) ; 
printf("PM  revision  is  %d  ".IVer); 
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WinQueryWindow 
Query  Window 


#define  INCL_WINWINDOWMGR  /*  Or  use  INCL_WIN  or  INCL_PM  7 


HWND  WinQueryWindow  (HWND  hwnd,  LONG  ICode) 


This  function  returns  the  handle  of  a window  that  has  a specified  relationship  to  a specified  window. 


Parameters 

hwnd  (HWND)  - input 

Handle  of  window  to  query. 

ICode  (LONG)  - input 

Type  of  window  information. 

Determines  what  window  information  is  returned: 


QW_NEXT 

QW_PREV 

QW_TOP 

QW_BOTTOM 

QWOWNER 

QWPARENT 

QW_NEXTTOP 


QW_PREVTOP 


Next  window  in  z-order  (window  below). 

Previous  window  in  z-order  (window  above). 

Topmost  child  window. 

Bottommost  child  window. 

Owner  of  window. 

Parent  of  window. 

Returns  the  next  window  of  the  owner  window  hierarchy  subject  to  their 
z-ordering. 

The  enumeration  is  evaluated  in  this  order: 

1.  The  hierarchy  of  windows  owned  by  this  window  in  their  z-order. 

2.  The  hierarchy  of  windows  of  the  next  z-ordered  window  having  the 
same  owner  as  this  window. 

3.  The  hierarchy  of  windows  in  their  z-order  having  the  same  owner  as 
the  owner  of  this  window.  This  step  is  repeated  until  the  top  of  the 
owner  tree  for  this  window  is  reached. 

4.  The  hierarchy  of  windows  in  their  z-order  of  unowned  windows. 

Returns  the  previous  main  window,  in  the  enumeration  order  defined  by 
QW_NEXTTOP. 


QWFRAMEOWNER  Returns  the  owner  of  hwnd  normalized  so  that  if  shares  the  same  parent 
as  hwnd. 


Returns 

Window  handle. 

Handle  of  window  related  to  hwnd. 

Possible  returns  from  WinGetLastError 

PMERR  INVALID  HWND  An  invalid  window  handle  was  specified. 

PMERR_PARAMETER_OUT_OF_RANGE  The  value  of  a parameter  was  not  within  the  defined  valid 

range  for  that  parameter. 
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WinQueryWindow  - 
Query  Window 


Remarks 

If  this  function  is  used  to  enumerate  windows  of  other  threads,  it  cannot  be  ensured  that  all  the 
windows  are  enumerated,  because  the  z-ordering  of  the  windows  can  change  during  the 
enumeration.  WinGetNextWindow  must  be  used  for  this  purpose. 

If  this  function  is  called  with  QW_OWNER  or  QW_PARENT,  the  return  value  is 
WinQueryDesktopWindow(hab,  NULLHANDLE),  and  not  HWND_DESKTOP,  when  the  desktop  window 
is  reached. 

If  this  function  is  called  with  QW_PARENT  for  an  object  window,  the  return  value  is  the  handle  of  the 
object  window  associated  with  the  desktop  window  as  returned  by  the  WinQueryObjectWindow 
function. 

Related  Functions 

• WinBeginEnumWindows 

• WinEndEnumWindows 

• WinEnumDIgltem 

• WinGetNextWindow 

• WinlsChild 

• WinMultWindowFromIDs 

• WinSetOwner 

• WinSetParent 

Example  Code 

This  example  shows  how  to  get  the  frame  window  handle  from  the  client  window  handle. 

Idefine  INCL_WINWINDOWMGR 
Idefine  INCL_WINACCELERATORS 
#include  <0S2.H> 

HACCEL  haccel ; 

HWND  hwndFrame,  hwndClient;  /*  window  handles.  */ 

HAB  hab;  /*  anchor  block.  */ 

hwndFrame  = WinQueryWindow(hwndClient, 

QW_PARENT);  /*  get  handle  of  parent,  */ 

/*  which  is  frame  window.  */ 
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WinQueryWindowDC  - 
Query  Window  Device  Context 


#define  INCL_WINWINDOWMGR  /*  Or  use  INCL_WIN  or  INCL_PM  7 


HDC  WinQueryWindowDC  (HWND  hwnd) 


This  function  returns  the  device  context  for  a given  window. 

Parameters 

hwnd  (HWND)  - input 
Window  handle. 


Returns 

Device-context  handle: 

NULLHANDLE  Either  WinOpenWindowDC  has  not  been  called  for  this  window,  or  an  error  has 
occurred. 

Other  Device  context  handle. 

Possible  returns  from  WinGetLastError 

PMERR  INVALID  HWND  An  invalid  window  handle  was  specified. 

Remarks 

A handle  is  returned  only  if  a device  context  has  been  opened  for  the  window  with 
WinOpenWindowDC. 


Related  Functions 

• WinEnableWindow 

• WinlsThreadActive 

• WinlsWindow 

• WinlsWindowEnabled 

• WinQueryDesktopWindow 

• WinQueryObjectWindow 

• WinQueryWindowProcess 

• WinQueryWindowRect 

• WinWindowFromDC 

• WinWindowFromID 

• WinWindowFromPoint 

Example  Code 

This  example  shows  how  to  check  if  WinOpenWindowDC  has  been  called  for  this  window. 

fdefine  INCL_WINWINDOWMGR 
linclude  <0S2.H> 

HWND  hwndClient;  /*  window  handle.  */ 

i f (Wi nQueryWi ndowDC ( hwndCl i ent ) ) 

{ 

/*  ...  */ 

} 
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WinQueryWindowModel  - 
Query  Window  Model 


#define  INCL_WINTHUNKAPI  /*  Or  use  INCL_WIN  or  INCL_PM  */ 


ULONG  WinQueryWindowModel  (HWND  hwnd) 


This  function  queries  the  memory  model  associated  with  a window. 


Parameters 

hwnd  (HWND)  - input 
Window  handle. 


Returns 

Memory  model  associated  with  the  window: 

PM_MODEL_1X  The  16-bit  memory  model  of  the  80386  processor. 

PM_MODEL_2X  The  32-bit  memory  model  of  the  80386  processor. 

Remarks 

This  function  enables  an  application  to  query  the  memory  model  associate  with  a particular  window 
to  find  out  whether  or  not  conversion  of  application-defined  data  is  required.  This  may  be  necessary, 
for  example,  when  sending  DDE  data.  An  existing  OS/2  Version  1.1  or  1.2  application  does  not  know 
about  pointer  conversion,  so  its  data  has  to  be  converted  for  use  in  a 32-bit  application. 

The  memory  model  is  determined  by  how  the  window  procedure  was  registered.  If  an  application 
calls  WinRegisterClass  from  32-bit  code,  any  windows  created  with  that  class  are  called  32-bit 
windows.  If  the  application  calls  WinSubclassWindow  from  16-bit  code  on  a 32-bit  window,  that 
window  becomes  a 16-bit  window. 

Related  Functions 

• WinQueryClassThunkProc 

• WinQueryWindowThunkProc 

• WinSetClassThunkProc 

• WinSetWindowThunkProc 

Example  Code 

This  example  shows  how  to  check  if  WinOpenWindowDC  has  been  called  for  this  window. 

Idefine  INCL_WINH00KS 
Idefine  INCL_WINTHUNKAPI 
linclude  <0S2.H> 

HWND  hwndClient;  /*  window  handle.  */ 

if  (WinQueryWindowModel  (hwndClient)  ==  PM_M0DEL_2X) 

{ 

/*  The  32-bit  memory  model  of  the  80386  processor.  */ 

} 
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WinQueryWindowPos  - 
Query  Window  Position 


#define  INCL_WINWINDOWMGR  /*  Or  use  INCL_WIN  or  INCL_PM  */ 


BOOL  WinQueryWindowPos  (HWND  hwnd,  PSWP  pswp) 


This  function  queries  the  window  size  and  position  of  a visible  window. 


Parameters 

hwnd  (HWND)  - input 
Window  handle. 

pswp  (PSWP)  - output 
SWP  structure. 

The  fields  are  set  such  that  a call  to  WinSetWindowPos  with  those  values  sets  the  window  to  its 
current  size  and  position,  with  the  exception  of  the  f /Options  bits  which  are  set  as  follows: 

• SWP_MOVE  and  SWP_SIZE  are  set  to  TRUE. 

• SWP_ACTIVATE  and  SWP_DEACTIVATE,  are  set  to  the  current  state  of  the  window. 

• If  the  window  is  minimized,  SWP_MINIMIZE,  is  set  and  SWP_MAXIMIZE,  is  zero. 

• If  the  window  is  maximized,  SWP_MAXIMIZE,  is  set  and  SWP_MINIMIZE,  is  zero. 

• If  the  window  is  neither  minimized  nor  maximized,  both  SWP_MINIMIZE,  and 
SWP_MAXIMIZE,  are  zero. 

• All  other  bits  are  set  to  zero. 


Returns 

Success  indicator: 

TRUE  Successful  completion 
FALSE  Error  occurred. 

Possible  returns  from  WinGetLastError 

PMERR  INVALID  HWND  An  invalid  window  handle  was  specified. 

PMERR_INVALID_FLAG  An  invalid  bit  was  set  for  a parameter.  Use  constants 

defined  by.  PM  for  options,  and  do  not  set  any  reserved 
bits. 


Related  Functions 

• WinGetMinPosition 

• WinQueryActiveWindow 

• WinSaveWindowPos 

• WinSetActiveWindow 

• WinSetMultWindowPos 

• WinSetWindowPos 
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WinQueryWindowPos  - 
Query  Window  Position 


Example  Code 

This  example  shows  how  to  center  a dialog  box  within  the  Screen  using  WinQueryWindowPos. 

Idefine  INCL_WINWINDOWMGR 
fdefine  INCL_WINSYS 
#i ncl ude  <0S2.H> 

HWND  hwnd;  /*  window  handle.  */ 

SHORT  ix,  iy; 

SHORT  i width,  i depth; 

SWP  swp; 

/*  Query  width  and  height  of  Screen  device  */ 

i width  = WinQuerySysValue(  HWND_DESKTOP,  SV_CXSCREEN  ); 
idepth  = WinQuerySysValue(  HWND_DESKTOP,  SV_CYSCREEN  ); 

/*  Query  width  and  height  of  dialog  box  */ 

WinQueryWindowPos(  hwnd,  (PSWP)&swp  ); 

/*  Center  dialog  box  within  the  Screen  */ 

ix  = (SHORT) ((  iwidth  - swp.cx  ) / 2); 
iy  = (SHORT) ( ( idepth  - swp.cy  ) / 2); 

WinSetWindowPos(  hwnd,  HWND_T0P,  ix,  iy,  0,  0,  SWP_M0VE  ); 
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WinQueryWindowProcess 
Query  Window  Process 


#define  INCL_WINWINDOWMGR  /*  Or  use  INCL_WIN  or  INCL_PM  */ 


BOOL  WinQueryWindowProcess  (HWND  hwnd,  PPID  pldpld,  PTID  pldtld) 


This  function  obtains  the  process  identity  and  thread  identity  of  the  thread  that  created  a window. 


Parameters 

hwnd  (HWND)  - input 
Window  handle. 

pldpld  (PPID)  - output 

Process  identity  of  the  thread  that  created  the  window, 
pldtld  (PTID)  - output 

Thread  identity  of  the  thread  that  created  the  window. 


Returns 

Success  indicator: 

TRUE  Successful  completion 
FALSE  Error  occurred. 

Possible  returns  from  WinGetLastError 

PMERR  INVALID  HWND  An  invalid  window  handle  was  specified. 

Related  Functions 

• WinEnableWindow 

• WinlsThreadActive 

• WinlsWindow 

• WinlsWindowEnabled 

• WinQueryDesktopWindow 

• WinQueryObjectWindow 

• WinQueryWindowDC 

• WinQueryWindowRect 

• WinWindowFromDC 

• WinWindowFromID 

• WinWindowFromPoint 
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WinQueryWindowProcess  - 
Query  Window  Process 


Example  Code 

This  example  shows  how  to  query  a window's  process  and  use  that  information  to  add  a switch  entry, 
window. 

Idefine  INCL_WINWINDOWMGR 
Idefine  INCL_WINSYS 
linclude  <0S2.H> 

HWND  hwndFrame;  /*  window  handle.  */ 

SWCNTRL  swctl ; 

PID  pid; 

TID  tid; 

HSWITCH  hsw; 

char  szT i tl e []  = "app.exe"; 

WinQueryWindowProcess(  hwndFrame,  &pid,  &tid); 

swctl. hwnd  = hwndFrame; 

swctl .idProcess  = pid; 

strcpy(  swctl .szSwtitle,  szTitle); 

hsw  = WinAddSwitchEntry(  &swctl); 
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WinQueryWindowPtr  - 
Query  Window  Pointer 


#define  INCL_WINWINDOWMGR  /*  Or  use  INCL_WIN  or  INCL_PM  7 


PVOID  WinQueryWindowPtr  (HWND  hwnd,  LONG  lb) 


This  function  retrieves  a pointer  value  from  the  memory  of  the  reserved  window  word. 


Parameters 

hwnd  (HWND)  - input 

Window  handle  which  has  the  pointer  to  retrieve. 

lb  (LONG)  - input 
Index. 

Zero-based  index  of  the  pointer  value  to  retrieve.  The  units  of  b are  bytes.  Valid  values  are 
zero  through  ( usExtra  —4),  where  usExtra  is  the  parameter  in  WinRegisterClass  that  specifies 
the  number  of  bytes  available  for  application-defined  storage. 

The  value  QWP_PFNWP  can  be  used  for  the  address  of  the  window’s  window  procedure. 


Returns 

Pointer  value. 

NULL  Error  occurred. 

Other  Pointer  value. 

Possible  returns  from  WinGetLastError 

PMERR  INVALID  HWND  An  invalid  window  handle  was  specified. 

PMERR_PARAMETER_OUT_OF_RANGE  The  value  of  a parameter  was  not  within  the  defined  valid 

range  for  that  parameter. 


Remarks 

The  lb  parameter  is  valid  only  if  all  of  the  bytes  referenced  are  within  the  reserved  memory. 


Related  Functions 

• WinQueryWindowULong 

• WinQueryWindowUShort 

• WinSetWindowBits 

• WinSetWindowPtr 

• WinSetWindowULong 

• WinSetWindowUShort 
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WinQueryWindowPtr  - 
Query  Window  Pointer 


Example  Code 

This  function  retrieves  a pointer  value  from  the  memory  of  the  reserved  window  word. 


MyWi ndowProc ( HWND  hwnd,  ULONG  msg,  MPARAM  mpl,  MPARAM  mp2) 

{ 

MYINSTANCEDATA  *InstanceData;  /*  application  defined  structure  */ 

switch  (msg)  { 
case  WM_CREATE: 

DosAl 1 ocMem(&InstanceData , si zeof (MYINSTANCEDATA) , fALLOC) ; 

/*  WindowProcedure  initializes  instance  data  for  this  window  */ 


/*  set  pointer  to  instance  in  window  words  */ 
WinSetWindowPtr(hwnd,  0,  InstanceData) ; 
break; 

case  WMUSER  + 1:  /*  application  defined  message  */ 

/*  Window  procedure  retrieves  instance  data  to  */ 
/*  process  this  message  */ 

InstanceData  = WinQueryWindowPtr(hwnd,  0); 


break; 
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WinQueryWindowRect  - 
Query  Window  Rectangle 


#define  INCL_WINWINDOWMGR  /*  Or  use  INCL_WIN  or  INCL_PM.  Also  in  COMMON  section  */ 


BOOL  WinQueryWindowRect  (HWND  hwnd,  PRECTL  prciRect) 


This  function  returns  a window  rectangle. 


Parameters 

hwnd  (HWND)  - input 

Window  handle  whose  rectangle  is  retrieved. 

prciRect  (PRECTL)  - output 
Window  rectangle. 

Window  rectangle  of  hwnd,  in  window  coordinates. 

Note:  The  value  of  each  field  in  this  structure  must  be  in  the  range  —32  768  through  32  767.  The 
data  type  WRECT  may  also  be  used,  if  supported  by  the  language. 


Returns 

Rectangle-returned  indicator: 

TRUE  Rectangle  successfully  returned 
FALSE  Rectangle  not  successfully  returned. 

Possible  returns  from  WinGetLastError 

PMERR  INVALID  HWND  An  invalid  window  handle  was  specified. 

Remarks 

The  rectangle  is  in  window  coordinates  relative  to  itself,  so  that  the  bottom  left  corner  is  at  the 
position  (0,0). 

If  the  size  of  a frame  window  has  been  changed  to  zero  by  WinSetWindowPos  or 
WinSetMultWindowPos,  the  original  size  is  returned  because  the  window  is  hidden,  not  sized,  in  this 
instance. 

Related  Functions 

• WinEnableWindow 

• WinlsThreadActive 

• WinlsWindow 

• WinlsWindowEnabled 

• WinQueryDesktopWindow 

• WinQueryObjectWindow 

• WinQueryWindowDC 

• WinQueryWindowProcess 

• WinWindowFromDC 

• WinWindowFromID 

• WinWindowFromPoint 
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WinQueryWindowRect  - 
Query  Window  Rectangle 


Example  Code 

This  example  gets  the  dimensions  of  the  window  and  calls  WinlnvalidateRect  to  invalidate  the 
window.  The  application  will  be  sent  a WMPAINT  message  with  the  entire  window  as  the  update 
rectangle. 

Idefine  INCL_WINWINDOWMGR 
linclude  <0S2.H> 

HAB  hab; 

HWND  hwnd; 

RECTL  rcl ; 


WinQueryWindowRect(hwnd,  &rcl); 

Winlnval idateRect(hwnd,  /*  window  to  invalidate  */ 

&rcl , /*  invalid  rectangle  */ 

FALSE);  /*  do  not  include  children  */ 
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WinQueryWindowText 
Query  Window  Text 


#define  INCL_WINWINDOWMGR  /*  Or  use  INCL_WIN  or  INCL_PM  */ 


LONG  WinQueryWindowText  (HWND  hwnd,  LONG  ILength,  PCH  pchBuffer) 


This  function  copies  window  text  into  a buffer. 


Parameters 

hwnd  (HWND)  - input 
Window  handle. 

If  hwnd  is  a frame-window  handle,  the  title-bar  window  text  is  copied. 

ILength  (LONG)  - input 
Length. 

Length  of  pchBuffer. 

pchBuffer  (PCH)  - output 
Window  text. 


Returns 

Length  of  returned  text. 

Possible  returns  from  WinGetLastError 

PMERR  INVALID  HWND  An  invalid  window  handle  was  specified. 

Remarks 

If  the  window  text  is  longer  than  (ILength— 1)  only  the  first  (ILength— 1)  characters  of  window  text  are 
copied. 

If  the  window  is  the  frame  window,  the  title  bar  window  text  is  copied. 

This  function  sends  a WM_QUERYWINDOWPARAMS  message  to  hwnd. 

If  this  function  references  the  window  of  another  process,  pchBuffer  must  be  in  memory  that  is 
shared  by  both  processes,  otherwise  a memory  fault  can  occur. 


Related  Functions 

• WinQueryDIgltemShort 

• WinQueryDIgltemText 

• WinQueryDIgltemTextLength 

• WinQueryWindowTextLength 

• WinSetDIgltemShort 

• WinSetDIgltemText 

• WinSetWindowText 

Related  Messages 

• WM_QUERYWINDOWPARAMS 
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WinQueryWindowText  - 
Query  Window  Text 


Example  Code 

This  example  shows  how  to  query  window  text. 


Idefine  INCL_WINWINDOWMGR 
linclude  <0S2.H> 

Idefine  FID_CLIENT  255 
HWND  hwndFrame; 

HWND  hwndClient; 
char  szTitle[32] ; 

/* 


This  function  creates  a new  window  of 
class  Generic 
and  returns  hwnd. 


hwndClient  = WinCreateWindow(hwndFrame, 

"Generic", 

(PSZ) "My  Window", 


0UL, 

0,0, 0,0, 
(HWND)NULL, 
HWND_T0P, 
FID_CLIENT, 
NULL, 

NULL); 


/* 

/* 

/* 

/* 

/* 

/* 

/* 


/*  no  window  text.  */ 
no  window  style.  */ 
position  and  size.  */ 
no  owner.  */ 
on  top  of  siblings  */ 
client  window  id.  */ 
control  data.  */ 
pres,  params.  */ 


WinQueryWindowText(hwndFrame,  sizeof(szTitle) , szTitle); 
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WinQuery  WindowT  extLength 
Query  Window  Text  Length 


#define  INCL_WINWINDOWMGR  /*  Or  use  INCL_WIN  or  INCL_PM  */ 


LONG  WinQuery  WindowT  extLength  (HWND  hwnd) 


This  call  returns  the  length  of  the  window  text,  excluding  any  null  termination  character. 


Parameters 

hwnd  (HWND)  - input 
Window  handle. 


Returns 

Length  of  the  window  text. 

Possible  returns  from  WinGetLastError 

PMERRINVALIDHWND  An  invalid  window  handle  was  specified. 


Remarks 

This  function  sends  a WMQUERYWINDOWPARAMS  message  to  hwnd. 


Related  Functions 

• WinQueryDIgltemShort 

• WinQueryDIgltemText 

• WinQueryDIgltemTextLength 

• WinQueryWindowText 

• WinSetDIgltemShort 

• WinSetDIgltemText 

• WinSetWindowText 

Related  Messages 

• WM_QUERYWINDOWPARAMS 


Example  Code 

This  example  shows  how  to  get  the  tile-bar  window  text. 

Idefine  INCLJIINWINDOWMGR 
Idefine  INCL_DOSMEMMGR 
finclude  <0S2.H> 

HWND  hwndFrame; 

PSZ  szTitle; 

ULONG  cbBytes; 


cbBytes  = WinQueryWindowTextLength(hwndFrarae) ; 

DosAl 1 ocMem( (PPVOID)szTi  tl  e, 

(ULONG) cbBytes, 

PAG_READ  | 

PAG_WRITE  | 

PAG_COMMIT) ; 

WinQueryWindowText (hwndFrame,  si zeof (szTitle) , szTitle); 
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WinQueryWindowThunkProc  - 
Query  Window  Pointer-Conversion  Procedure 


#define  INCL_WINTHUNKAPI  /*  Or  use  INCL.WIN  or  INCL_PM  */ 


PFN  WinQueryWindowThunkProc  (HWND  hwnd) 


This  function  queries  the  pointer-conversion  procedure  associated  with  a window. 


Parameters 

hwnd  (HWND)  - input 
Window  handle. 


Returns 

Pointer-conversion  procedure  identifier: 

NULL  No  pointer-conversion  procedure  is  associated  with  this  window. 

Other  Identifier  of  the  pointer-conversion  procedure  associated  with  this  window. 

Related  Functions 

• WinQueryClassThunkProc 

• WinQueryWindowModel 

• WinSetClassThunkProc 

• WinSetWindowThunkProc 

Example  Code 

This  example  shows  how  to  get  pointer  conversion  procedure  associated  with  the  frame  window. 

Idefine  INCL_WINTHUNKAPI 
linclude  <0S2.H> 

HWND  hwnd Frame; 

PFN  pthnkproc; 


pthnkproc  = WinQueryWindowThunkProc(hwndFrame) ; 
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WinQueryWindowllLong  - 
Query  Window  Long 


#define  INCL_WINWINDOWMGR  /*  Or  use  INCL_WIN  or  INCL_PM  */ 


ULONG  WlnQueryWindowULong  (HWND  hwnd,  LONG  lb) 


This  function  obtains  the  unsigned  long  integer  value,  at  a specified  offset,  from  the  memory  of  a 
reserved  window  word,  of  a given  window. 


Parameters 

hwnd  (HWND)  - input 

Handle  of  window  to  be  queried. 

lb  (LONG)  - input 
Index. 

Zero-based  index  into  the  window  words  of  the  value  to  be  queried.  The  units  of  b are  bytes. 
Valid  values  are  zero  through  (usExtra  —4),  where  usExtra  is  the  parameter  in  WinRegisterClass 
that  specifies  the  number  of  bytes  available  for  application-defined  storage.  Any  of  the  QWL_* 
values,  are  also  valid. 

Note:  QWS_*  values  cannot  be  used. 

QWL_HMQ  Handle  of  message  queue  of  window.  Note  that  the  leading  16  bits  of 

this  value  are  zero. 

QWL_STYLE  Window  style. 

QWL_HHEAP  Heap  handle  used  by  child  windows  of  this  window. 

QWL_HWNDFOCUSSAVE  Window  handle  of  the  child  windows  of  this  window  that  last 

possessed  the  focus  when  this  frame  window  was  last  deactivated. 

QWL_USER  A ULONG  value  for  applications  to  use  is  present  at  offset 

QWLJJSER  in  windows  of  the  following  preregistered  window 
classes: 

WC_FRAME  (includes  dialog  windows) 

WC_LISTBOX 

WC_BUTTON 

WC_STATIC 

WC_ENTRYFIELD 

WC_SCROLLBAR 

WC_MENU 

This  value  can  be  used  to  place  application-specific  data  in  controls. 

QWL_DEFBUTTON  The  default  pushbutton  for  a dialog. 

The  default  pushbutton  is  the  one  that  sends  its  WM  COMMAND 
message  when  the  enter  key  is  pressed. 

Other  Zero-based  index. 

Returns 

Value  contained  in  the  window  word. 

Possible  returns  from  WinGetLastError 

PMERR  INVALID  HWND  An  invalid  window  handle  was  specified. 

PMERR_PARAMETER_OUT_OF_RANGE  The  value  of  a parameter  was  not  within  the  defined  valid 

range  for  that  parameter. 
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WinQueryWindowULong  - 
Query  Window  Long 


Remarks 

The  window  handle  that  is  passed  to  this  function  can  be  the  handle  of  a window  with  the  same,  or 
different,  message  queue  as  the  caller,  thereby  allowing  the  caller  to  obtain  data  from  windows 
belonging  to  other  threads. 

The  specified  lb  is  valid  only  if  all  of  the  bytes  referenced  are  within  the  reserved  memory. 

Related  Functions 

• WinQueryWindowPtr 

• WinQueryWindowUShort 

• WinSetWindowBits 

• WinSetWindowPtr 

• WinSetWindowULong 

• WinSetWindowUShort 

Example  Code 

This  example  shows  how  to  get  the  handle  of  the  message  queue  of  a window. 

Idefine  INCL_WINWINDOWMGR 
linclude  <0S2.H> 

HWNO  hwnd; 

HMQ  hmq; 

hmq  = (HMQ)WinQueryWindowULong(hwnd,  QWL_HMQ); 
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Query  Window  Short 


#define  INCL_WINWINDOWMGR  /*  Or  use  INCL_WIN  or  INCL_PM  */ 


ULONG  WinQueryWindowUShort  (HWND  hwnd,  LONG  lb) 


This  function  obtains  the  unsigned  short  integer  value  at  a specified  offset  from  the  reserved  window 
word’s  memory  of  a given  window. 


Parameters 

hwnd  (HWND)  - input 

Handle  of  window  to  be  queried. 

lb  (LONG)  - input 
Index. 


Zero-based  index  into  the  window  words  of  the  value  to  be  queried.  The  units  of  b are  bytes. 
Valid  values  are  zero  through  (usExtra  —2),  where  usExtra  is  the  parameter  in  WinRegisterClass 
that  specifies  the  number  of  bytes  available  for  application-defined  storage.  Any  of  the  QWS_* 
values,  are  valid. 


Note:  QWL_*  values  cannot  be  used. 


QWSJD 

QWSFLAGS 


Window  identity.  The  value  of  the  Id  parameter  of  the  WinCreateWindow 
function. 


These  indicators  apply  only  to  frame  or  dialog  windows,  and  contain 
combinations  of  the  following  indicators: 


FF_FLASHWINDOW 

FF_ACTIVE 

FFSELECTED 

FFFLASHHILITE 

FFOWNERHIDDEN 


FFDLGDISMISSED 

FFOWNERDISABLED 


Frame  window  is  flashing. 

Frame  window  is  displayed  in  the  active  state. 
Frame  window  is  selected. 

Window  is  currently  flashed.  This  indicator 
toggles  with  each  flash. 

Frame  window  is  hidden  as  a result  of  its  owner 
being  hidden  or  minimized.  This  indicator  is  set 
only  if  the  window  and  its  owner  are  siblings. 
Dialog  has  been  dismissed  by  the  WinDismissDIg 
function. 

Window’s  owner  is  disabled.  This  indicator  is  only 
set  if  the  window  and  its  owner  are  siblings. 


QWS_RESULT 

QWSXRESTORE 

QWSYRESTORE 

QWSCXRESTORE 

QWS_CYRESTORE 


Dialog-result  parameter,  as  established  by  the  WinDismissDIg  function. 
The  x-coordinate  of  the  position  to  which  the  window  is  restored. 

See  also  the  QWS_CYRESTORE  value. 

The  y-coordinate  of  the  position  to  which  the  window  is  restored. 

See  also  the  QWS_CYRESTORE  value. 

The  width  to  which  the  window  is  restored. 

See  also  the  QWS_CYRESTORE  value. 

The  height  to  which  the  window  is  restored. 

These  values  are  only  valid  while  the  window  is  maximized  or  minimized 
(that  is,  while  either  the  WS_MINIMIZED  or  WS_MAXIMIZED  window  style 
indicators  are  set).  Changing  these  values  with  the  WinSetWindowUShort 
call  alters  the  restore  size  and  position. 
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QWS_XMINIMIZE  The  x-coordinate  of  the  position  to  which  the  window  is  minimized.  If  this 
value  is  —1,  the  window  has  not  been  minimized. 

See  also  the  QWS_YMINIMIZE  value. 

QWS_YMINIMIZE  The  y-coordinate  of  the  position  to  which  the  window  is  minimized. 

When  the  window  is  minimized  for  the  first  time  an  arbitrary  position  is 
chosen.  Changing  these  values  with  the  WinSetWindowUShort  call  alters 
the  position  of  the  minimized  window,  but  only  when  the  window  is  not  in  a 
minimized  state. 


Other 


Zero-based  index. 


Returns 

Value  contained  in  the  indicated  window  word. 

Possible  returns  from  WinGetLastError 

PMERRJNVALID  HWND  An  invalid  window  handle  was  specified. 

PMERR_PARAMETER_OUT_OF_RANGE  The  value  of  a parameter  was  not  within  the  defined  valid 

range  for  that  parameter. 

Remarks 

The  window  handle  that  is  passed  to  this  function  can  be  the  handle  of  a window  with  the  same,  or 
different,  message  queue  as  the  caller,  thereby  allowing  the  caller  to  obtain  data  from  windows 
belonging  to  other  threads. 


Related  Functions 

• WinQueryWindowPtr 

• WinQueryWindowULong 

• WinSetWindowBits 

• WinSetWindowPtr 

• WinSetWindowULong 

• WinSetWindowUShort 

Related  Messages 

• WM_COMMAND 

Example  Code 

In  this  example,  the  WinQueryWindowUShort  call  is  used  to  query  the  window  words  to  see  if  a 
window  has  been  minimized. 

Idefine  INCL_WINWINDOWMGR 
linclude  <0S2.H> 

HWND  hwnd; 

USHORT  usResult; 

usResult  = WinQueryWindowUShort (hwnd,  QWS_XMINIMIZE) ; 
if  (-1  ==  (LONG) usResult) 

{ 

/*  window  has  not  been  minimized.  */ 

} 
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WinQueryObject  - 

Query  Workplace  Object  Handle 


#define  INCL_WINWORKPLACE 


HOBJECT  WinQueryObject  (PSZ  pszObjectID) 


The  WinQueryObject  function  returns  a handle  to  the  given  object 


Parameters 

pszObjectID  (PSZ)  - input 

The  ObjectID  of  an  existing  object,  for  example  < WP_DESKTOP> , or  alternatively  the  fully 
qualified  filename  of  any  file  or  directory. 


Returns 

MRESULT 

Persistent  object  handle,  or  NULLHANDLE  if  the  object  does  not  exist  or  could  not  be  awakened. 


Remarks 

This  function  allows  you  to  obtain  the  persistant  object  handle  for  any  file  object,  by  passing  the  fully 
qualified  filename.  Similarly  any  objects'  handle  can  be  retrieved  if  its  ObjectID  string  is  passed. 
Once  a program  has  an  object  handle,  it  is  able  to  change  the  objects  state  by  using  the 
WinSetObjectData  function  or  delete  the  object  using  the  WinDestroyObject  function.  Note  that  valid 
ObjectID  strings  must  always  start  with  the ' < ' character  and  be  terminated  by  the  ' > ' character, 
and  are  thus  invalid  file  system  names. 


Related  Functions 

• WinCreateObject 

• WinDestroyObject 

• WinSetObjectData 
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Realize  Palette 


#define  INCL_WIN  /*  Or  use  INCL_PM  */ 


LONG  WinRealizePalette  (HWND  hwnd,  HPS  hps,  PULONG  pcclr) 


This  function  indicates  that  drawing  is  about  to  take  place  after  a palette  has  been  selected. 


Parameters 

hwnd  (HWND)  - input 

Window  handle  where  drawing  is  taking  place. 

hps  (HPS)  - input 

Presentation-space  handle. 

pcclr  (PULONG)  - output 

Number  of  physical  palette  entries  changed 


A value  of  zero  indicates  that  the  palette  was  successfully  realized  without  changing  any  entries 
in  the  display  hardware  physical  table.  A non-zero  value  gives  the  number  of  hardware  table 
entries  that  were  changed  and  indicates  that  a WM  REALIZEPALETTE  message  has  been  posted 
to  all  other  applications. 


Returns 

Number  of  colors  remapped. 

PAL_ERROR  Error  occurred 

Otherwise  Number  of  colors  that  are  remapped.  This  includes  both  animating  and 
non-animating  indexes  that  have  matches  in  the  physical  palette.  This 
information  can  be  used  to  determine  whether  the  window  needs  repainting. 

Note  that  this  information  may  already  be  out  of  date  if  there  are  other 
palette-using  applications  running. 


Possible  returns  from  WinGetLastError 


PMERR_NO_PALETTE_SELECTED 

PMERRJNVALIDHWND 

PMERRINVHDC 

PMERRHDCBUSY 

PMERRJNVINAREA 


An  attempt  to  realize  a palette  failed  because  no  palette 
was  previously  selected  into  the  Presentation  Space. 

An  invalid  window  handle  was  specified. 

An  invalid  device-context  handle  or  (micro  presentation 
space)  presentation-space  handle  was  specified. 

An  internal  device  context  busy  error  was  detected.  The 
device  context  was  locked  by  one  thread  during  an 
attempt  to  access  it  from  another  thread. 

An  attempt  was  made  to  issue  a function  invalid  inside  an 
area  bracket.  This  can  be  detected  while  the  actual 
drawing  mode  is  draw  or  draw-and-retaln  or  during 
segment  drawing  or  correlation  functions. 


Remarks 

This  function  is  typically  used  after  a GpiSelectPalette  function  or  in  response  to  a 
WM_REALIZEPALETTE  message.  It  causes  the  system  to  ensure  that  the  palette  is  appropriately 
realized  for  all  drawing  operations. 
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When  the  window.has  the  input  focus,  the  palette  will  be  realized  absolutely.  Otherwise,  the 
realization  is  on  a best-can-do  basis.  If  the  palette  is  larger  than  the  currently  associated  device  can 
support,  as  many  entries  as  possible  are  realized,  starting  from  the  lowest  index. 

If  the  presentation  space  is  currently  associated  with  a device  context  of  type  OD_MEMORY  (see 
DevOpenDC),  then  this  function  performs  no  function  other  than  returning  without  error. 

This  function  must  not  be  called  while  processing  a WM  SETFOCUS  message,  because  a window's 
activation  state  is  not  known  until  processing  of  this  message  is  complete. 

Note  that  the  palette  cannot  be  physically  changed  on  all  devices.  The  effect  of  this  call  is  therefore 
device  dependent. 


Related  Functions 

• WinBeginPaint 

• WinEnabfeWindowllpdate 

• WinEndPaint 

• WinExcludellpdateRegion 

• WinGetClipPS 

• WinGetPS 

• WinGetScreenPS 

• WinlnvalidateRect 

• WinlnvalidateRegion 

• WinlsWindowShowing 

• WinlsWindowVisible 

• WinLockVisRegions 

• WinOpenWindowDC 

• WinQueryUpdateRect 

• WinQueryllpdateRegion 

• WinReleasePS 

• WinShowWindow 

• WinllpdateWindow 

• WinValidateRect 

• WinValidateRegion 

Related  Messages 

• WM_SETFOCUS 

• WM  REALIZEPALETTE 


Example  Code 

In  this  example,  the  WinRealizePalette  call  is  issued  in  response  to  a WM_REALIZEPALETTE.  This 
ensures  that  the  palette  is  appropriately  realized  for  all  drawing  operations. 

Idefine  INCL_WIN 
finclude  <0S2.H> 

HWND  hwnd; 

ULONG  cclr; 

USHORT  msg; 

HPS  hps; 

switch(msg) 

{ 

case  WM_REALIZEPALETTE: 

Wi nReal i zePal ette (hwnd , hps , &ccl  r ) ; 

} 
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WinRegisterClass  - 
Register  Window  Class 


#define  INCL_WINWINDOWMGR  /*  Or  use  INCL_WIN  or  INCL_PM.  Also  in  COMMON  section  */ 


BOOL  WinRegisterClass  (HAB  hab,  PSZ  pszClassName,  PFNWP  pWndProc, 
ULONG  fICIassStyle,  USHORT  usExtra) 


This  function  registers  a window  class. 


Parameters 

hab  (HAB)  - input 

Anchor-block  handle. 

pszClassName  (PSZ)  - input 
Window-class  name. 

An  application-specified  class  name. 

pWndProc  (PFNWP)  - input 

Window-procedure  identifier. 

Can  be  NULL  if  the  application  does  not  provide  its  own  window  procedure. 

fICIassStyle  (ULONG)  - input 
Default-window  style. 

This  can  be  any  of  the  standard  class  styles  (CS_*)  (see  page  12-1)  in  addition  to  any 
class-specific  styles  that  are  defined.  These  styles  can  be  augmented  when  a window  of  this 
class  is  created. 

A public  window  class  is  created  if  the  CS_PUBLIC  style  is  specified,  otherwise  a private  class  is 
created.  The  CS_PUBLIC  style  must  only  be  specified  for  the  shell  process. 

Public  classes  are  available  for  creating  windows  from  any  process.  Private  classes  are  only 
available  to  the  registering  process. 

usExtra  (USHORT)  - input 
Reserved  storage. 

This  is  the  number  of  bytes  of  storage  reserved  per  window  created  of  this  class  for  application 
use. 


Returns 

Window-class-registration  indicator: 

TRUE  Window  class  successfully  registered 
FALSE  Window  class  not  successfully  registered. 


Possible  returns  from  WinGetLastError 

PMERRINVALIDFLAG 

PMERRINVALIDINTEGERATOM 
PMERRINVALIDHATOMTBL 
PMERRINVALIDATOMNAME 
P M E R R_ATOM_N  AM  ENOTFOUN  D 


An  invalid  bit  was  set  for  a parameter.  Use  constants 
defined  by  PM  for  options,  and  do  not  set  any  reserved 
bits. 

The  specified  atom  is  not  a valid  integer  atom. 

An  invalid  atom-table  handle  was  specified. 

An  invalid  atom  name  string  was  passed. 

The  specified  atom  name  is  not  in  the  atom  table. 
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Register  Window  Class 


Remarks 

When  an  application  registers  a private  class  with  the  window  procedure  in  a dynamic  link  library,  it 
is  the  application’s  responsibility  to  resolve  the  window-procedure  address  before  issuing  this 
function. 

A private  class  must  not  be  registered  with  the  same  name  as  a public  class  in  the  same  process. 

However,  if  a private  class  is  registered  with  the  same  name  as  one  that  already  exists,  the 
parameters  replace  the  old  class  parameters,  and  the  return  value  is  TRUE.  The  window  procedure 
of  an  existing  window  can  be  changed  using  WinSubclassWindow  or  WinSetWindowPtr.  The  style  of 
an  existing  window  can  be  changed  with  the  WinSetWindowULong  or  WinSetWindowUShort  functions 
The  number  of  bytes  of  storage  allocated  for  application  use  cannot  be  changed  once  the  window  is 
created. 

Private  classes  are  deleted  when  the  process  that  registers  them  terminates. 


Related  Functions 

• WinCalcFrameRect 

• WinCreateFrameControls 

• WinCreateStdWindow 

• WinCreateWindow 

• WinDefWindowProc 

• WinDestroyWindow 

• WinQueryClassInfo 

• WinQueryClassName 

• WinSubclassWindow 

Example  Code 

This  example  calls  WinRegisterClass  to  register  a class  or  returns  FALSE  if  an  error  occurs. 

fdefine  INCL_WINWINDOWMGR 
finclude  <0S2.H> 

HAB  hab; 

CHAR  szClassName[]  = "Generic";  /*  window  class  name  */ 

PFNWP  pGenericWndProc; 

if  (!WinRegisterClass(hab, 
szClassName, 
pGenericWndProc, 

0L, 

0)) 

return  (FALSE); 


/*  anchor-block  handle  */ 
/*  class  name  */ 
/*  window  procedure  */ 
/*  window  style  */ 


/*  amount  of  reserved  memory  */ 
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Register  Workplace  Object  Class 


#define  INCL_WINWORKPLACE 


BOOL  WinRegisterObjectClass  (PSZ  pszCiassName,  PSZ  pszModname) 


The  WinRegisterObjectClass  function  registers  a workplace  object  class. 


Parameters 

pszCiassName  (PSZ)  - input 

A pointer  to  a zero-terminated  string  which  contains  the  name  of  the  object  class  being 
registered  in  the  workplace. 

pszModname  (PSZ)  - input 

A pointer  to  a zero-terminated  string  which  contains  the  name  of  the  DLL  which  holds  the  object 
definition. 

Returns 

Success  indicator: 

TRUE  Successful  completion 
FALSE  Error  occurred. 

Remarks 

The  DLL  must  be  one  created  using  the  IBM  System  Object  Model.  Object  classes  will  automatically 
be  added  to  the  system  when  installing  a DLL  which  contains  an  object  definition.  Generally,  it  is  not 
required  for  the  object  DLL  to  be  present  at  the  time  WinRegisterObjectClass  is  called.  However,  if 
the  object  class  overrides  wpcisQuerylnstanceType  or  wpcisQuerylnstanceFilter,  the  DLL  must  be 
present  at  the  time  of  the  class  registration. 


Related  Functions 

• WinCreateObject 

• WinDeregisterObjectClass 

• WinReplaceObjectClass 
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WinRegisterUserDatatype 
Register  User  Data  Type 


#define  INCL_WINMESSAGEMGR  /*  Or  use  INCL_WIN  or  INCL_PM.  Also  in  COMMON  section  7 


BOOL  WinRegisterUserDatatype  (HAB  hab,  LONG  IDatatype,  LONG  ICount,  PSHORT  asTypes) 


This  function  registers  a data  type  and  defines  its  structure. 

Parameters 

hab  (HAB)  - input 

Anchor-block  handle. 

IDatatype  (LONG)  - input 

Data  type  code  to  be  defined. 

This  must  not  be  less  than  DTYPJJSER,  and  must  not  have  been  defined  previously. 

ICount  (LONG)  - input 
Number  of  elements. 

Must  not  be  less  than  one. 

asTypes  (PSHORT)  - input 

Data  type  codes  of  structure  components. 

Valid  data  types  are  the  system-defined  data  types  and  their  pointer  equivalents, 
application-defined  data  types  and  their  pointer  equivalents,  and  control  data  types.  Note  that 
not  all  of  the  data  types  that  occur  in  the  CPI  can  be  specified  on  this  function. 

A control  data  type  is  followed  by  one  or  more  entries  in  the  asTypes  array  that  are  interpreted 
in  a special  way.  Control  data  types  allow  arrays,  offsets,  and  lengths  to  be  defined. 

Simple  Data  Types: 

DTYP_ATOM 
DTYP_BIT16 
DTYP_BIT32 
DTYP_BIT8 
DTYP_BOOL 
DTYP_COUNT2 
DTYP_COUNT2B 
DTYP_COUNT2CH 
DTYP_COUNT4B 
DTYP_CPID 
DTYPERRORID 
DTYPJDENTITY 
DTYPJDENTITY4 
DTYPJNDEX2 
DTYPJPT 
DTYP_LENGTH2 
DTYP_LENGTH4 
DTYP_LONG 


See  ATOM  data  type. 
See  USHORT  data  type. 
See  ULONG  data  type. 
See  UCHAR  data  type. 
See  BOOL  data  type. 

See  USHORT  data  type. 
See  USHORT  data  type. 
See  USHORT  data  type. 
See  ULONG  data  type. 
See  USHORT  data  type. 
See  ERRORID  data  type. 
See  USHORT  data  type. 
See  ULONG  data  type. 
See  USHORT  data  type. 
See  IPT  data  type. 

See  USHORT  data  type. 
See  ULONG  data  type. 
See  LONG  data  type. 
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WinRegisterUserDatatype  - 
Register  User  Data  Type 

— 

DTYP0FFSET2B 

See  USHORT  data  type. 

DTYPPID 

See  PID  data  type. 

DTYPPIX 

See  PIX  data  type. 

DTYPPROGCATEGORY 

See  PROGCATEGORY  data  type. 

DTYP_PROPERTY2 

See  USHORT  data  type. 

— ■ 

DTYPPROPERTY4 

See  LONG  data  type. 

DTYPRESID 

See  HMODULE  data  type. 

DTYPSEGOFF 

See  NPBYTE  data  type. 

DTYPSHORT 

See  SHORT  data  type. 

DTYPTID 

See  TID  data  type. 

— 

DTYP_TIME 

See  LONG  data  type. 

DTYPUCHAR 

See  UCHAR  data  type. 

DTYPULONG 

See  ULONG  data  type. 

DTYPUSHORT 

See  USHORT  data  type. 

DTYPWIDTH4 

See  LONG  data  type. 

— 

DTYP_WNDPROC 

See  PFNWP  data  type. 

Handle  Data  Types : 

DTYPHAB 

See  HAB  data  type. 

DTYPHACCEL 

See  HACCEL  data  type. 

DTYP_HAPP 

See  HAPP  data  type. 

— ' 

DTYP_HATOMTBL 

See  HATOMTBL  data  type. 

DTYPHBITMAP 

See  HBITMAP  data  type. 

DTYP_HDC 

See  HDC datatype. 

DTYP_HENUM 

See  HENUM  data  type. 

DTYPHINI 

See  HINI  data  type. 

DTYPHLIB 

See  HUB  data  type. 

OTYP_HMF 

See  HMF  data  type. 

DTYP_HMQ 

See  HMQ  data  type. 

DTYPHPOINTER 

See  HPOINTER  data  type. 

DTYPHPROGRAM 

See  HPROGRAM  data  type. 

— 

DTYP_HPS 

See  HPS  data  type. 

DTYP_HRGN 

See  HRGN  data  type. 

DTYPHSEM 

See  HSEM  data  type. 

DTYPHSPL 

See  HSPL  data  type. 

DTYP_HS  WITCH 

See  HSWITCH  data  type. 

— 

DTYPHWND 

See  HWND  data  type. 

Character/String/Buffer  Data  Types: 

DTYPBYTE 

See  BYTE  data  type. 

DTYPCHAR 

See  GHAR  data  type. 

— 
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DTYP_STRL 

See  PSZ  data  type. 

DTYP_STR16 

See  STR16  data  type. 

DTYP_STR32 

See  STR32  data  type. 

DTYP_STR64 

See  STR64  data  type. 

DTYP_STR8 

See  STR8  data  type. 

Structure  Data  Types: 

DTYP_ACCEL 

See  ACCEL  data  type. 

DTYPACCE  LT ABLE 

See  ACCELTABLE  data  type. 

DTYPARCP  ARAMS 

See  ARCPARAMS  data  type. 

DTYPAREABUNDLE 

See  AREABUNDLE  data  type. 

DTYP_BITMAPINFO 

See  BITMAPINFO  data  type. 

DTYPBITMAPINFOHEADER 

See  BITMAPINFOHEADER  data  type. 

DT  YP_BTNCDAT  A 

See  BTNCDATA  data  type. 

DTYP_CATCHBUF 

See  CATCHBUF  data  type. 

DTYPCHARBUNDLE 

See  CHARBUNDLE  data  type. 

DTYP_CLASSINFO 

See  CLASSINFO  data  type. 

DTYP_CREATESTRUCT 

See  CREATESTRUCT  data  type. 

DTYPCURSORINFO 

See  CURSORINFO  data  type. 

DTYP_DEVOPENSTRUC 

See  DEVOPENSTRUC  data  type. 

DTYP_DLGTEMPLATE 

See  DLGTEMPLATE  data  type. 

DTYP_DLGTITEM 

See  DLGTITEM  data  type. 

DTYP_ENTRYFDAT  A 

See  ENTRYFDATA  data  type. 

DTYP_FATTRS 

See  FATTRS  data  type. 

DTYP_FFDESCS 

See  FFDESCS  data  type. 

DTYP_FIXED 

See  FIXED  data  type. 

DTYP_FONTMETRICS 

See  FONTMETRICS  data  type. 

DTYP_FRAM  ECDAT  A 

See  FRAMECDATA  data  type. 

DTYP_G  RADIENTL 

See  GRADIENTL  data  type. 

DTYP_HCINFO 

See  HCINFO  data  type. 

DTYPIMAGEBUNDLE 

See  IMAGEBUNDLE  data  type. 

DTYPKERNINGPAIRS 

See  KERNINGPAIRS  data  type. 

DTYPLINEBUNDLE 

See  LINEBUNDLE  data  type. 

DTYP_MARGSTRUCT 

See  MLEMARGSTRUCT  data  type. 

DTYPMARKERBUNDLE 

See  MARKERBUNDLE  data  type. 

DTYP_MATRIXLF 

See  MATRIXLF  data  type. 

DT YP_M  LECTLDAT A 

See  M LECTLDAT A data  type. 

DTYP_OVERFLOW 

See  MLEOVERFLOW  data  type. 

DTYPOWNERITEM 

See  OWNERITEM  data  type. 

DTYP_POINTERINFO 

See  POINTERINFO  data  type. 
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DTYPPOINTL 

See 

DTYPPROGRAMENTRY 

See 

DTYPPROGTYPE 

See 

DTYPQMSG 

See 

DTYPRECTL 

See 

DTYPRGB 

See 

DTYPRGNRECT 

See 

DTYPSBCDATA 

See 

DTYPSIZEF 

See 

DTYPSIZEL 

See 

DTYP_SWBLOCK 

See 

DTYPSWCNTRL 

See 

DTYP_SWENTRY 

See 

DTYPSWP 

See 

DTYPTRACKINFO 

See 

DTYPUSERBUTTON 

See 

DTYPWNDPARAMS 

See 

DTYPWPOINT 

See 

DTYPWRECT 

See 

DTYPXYWINSIZE 

See 

Pointer  Data  Types: 

POINTL  data  type. 
PROGRAMENTRY  data  type. 
PROGTYPE  data  type. 

QMSG  data  type. 

RECTL  data  type. 

RGB  datatype. 

RGNRECT  data  type. 
SBCDATA  data  type. 

SIZEF  data  type. 

SIZEF  data  type. 

SWBLOCK  data  type. 
SWCNTRL  data  type. 
SWENTRY  data  type. 

SWP  data  type. 

TRACKINFO  data  type. 
USERBUTTON  datatype. 
WNDPARAMS  data  type. 
WPOINT  data  type. 

WRECT  data  type. 
XYWINSIZE  data  type. 


DTYPPxxxx  Pointer  to  an  item  of  data  type  DTYPxxxx,  where  DTYPxxxx  is 

one  of  the  data  types  in  the  preceding  lists.  The  value  of  a 
pointer  data  type  is  the  value  of  the  corresponding  non-pointer 
data  type  prefixed  with  minus  to  make  it  negative. 

Minimum  Application  Data  Type : 

DTYPUSER  Minimum  value  for  application-defined  non-pointer  data  type. 

Control  Data  Types: 

DTYP_CTL_ARRAY  This  starts  a sequence  of  three  array  elements  that  define  an 

array;  the  array  resides  in  the  structure  being  defined,  and  may 
have  a fixed  number  of  elements,  or  a variable  number  of 
elements. 


Element  Value 

n DTYP_CTL_ARRAY 

n+1  data  type  of  array  data. 

n+2  minus  the  number  of  elements  in  the  array  (for  an 

array  of  fixed  size),  or  the  index  of  the  element  in 
asTypes  corresponding  to  the  structure  component 
which  contains  the  number  of  elements  in  the  array 
being  defined;  this  component  must  have  a suitable 
numeric  data  type;  the  array-size  element  must 
precede  element  ‘n’  in  asTypes.  The  index  is 
zero-based. 
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DTYP_CTL_LENGTH  This  starts  a sequence  of  four  array  elements  that  define  a 

structure  component  containing  the  length  of  part  or  all  of  the 
structure.  The  length  component  resides  at  this  point  in  the 
structure. 

Element  Value 

n DTYP_CTL_LENGTH 

n+1  data  type  of  structure  component  that  contains  the 

length  (must  be  a suitable  numeric  data  type). 

n+2  the  index  of  the  element  in  asTypes  corresponding  to 

the  first  structure  component  that  is  included  in  the 
length;  a value  of  —1  denotes  the  start  of  the 
structure.  The  index  is  zero-based. 

The  element  specified  must  not  be  one  that  is  the 
second  or  subsequent  element  in  a DTYP_CTL_* 
sequence  of  elements. 

n+3  the  index  of  the  element  in  asTypes  corresponding  to 

the  last  structure  component  that  is  included  in  the 
length;  it  must  not  be  less  than  the  value  contained  in 
element  n+2.  A value  of  — 1 denotes  the  end  of  the 
structure.  The  index  is  zero-based. 

The  element  specified  must  not  be  one  that  is  the 
second  or  subsequent  element  in  a DTYP_CTL_* 
sequence  of  elements. 

If  the  value  is  —1,  the  length  includes  all  offset  data 
residing  at  the  end  of  the  structure. 

DTYP_CTL_OFFSET  This  starts  a sequence  of  four  array  elements  that  define  data 

addressed  by  an  offset.  The  offset  resides  at  this  point  in  the 
structure,  and  contains  the  offset  in  bytes  of  the  data  from  the 
start  of  the  outermost  structure  in  which  this  component  resides. 
The  data  addressed  by  the  offset  must  occupy  storage  following 
the  fixed  part  of  the  structure.  The  data  may  be  scalar  data  or 
array  data. 

Element  Value 

n DTYP_CTL_OFFSET 

n+1  data  type  of  the  structure  component  that  contains 

the  offset  (must  be  a suitable  unsigned  numeric 
datatype). 

n+2  data  type  of  offset  data. 

n+3  minus  the  number  of  elements  in  the  array  (for  an 

array  of  fixed  size),  or  the  index  of  the  element  in 
asTypes  corresponding  to  the  structure  component 
that  contains  the  number  of  elements  in  the  array 
being  defined;  this  component  must  have  a suitable 
numeric  data  type;  the  array-size  element  may  occur 
earlier  or  later  in  the  structure.  The  index  is 
zero-based. 

A value  of  —1  indicates  that  the  data  is  not  an  array. 
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DTYP_CTL_PARRAY  This  starts  a sequence  of  three  array  elements  that  define  a 

pointer  to  an  array;  the  pointer  resides  at  this  point  in  the 
structure,  the  array  resides  elsewhere.  The  array  may  have  a 
fixed  or  variable  number  of  elements. 

Element  Value 

n DTYP_CTL_PARRAY 

n+1  data  type  of  array  data. 

n+2  minus  the  number  of  elements  in  the  array  (for  an 

array  of  fixed  size),  or  the  index  of  the  element  in 
asTypes  corresponding  to  the  structure  component 
that  contains  the  number  of  elements  in  the  array 
being  defined;  this  component  must  have  a suitable 
numeric  data  type.  The  array-size  element  may 
occur  earlier  or  later  in  the  structure.  The  index  is 
zero-based. 

Returns 

Success  indicator: 

TRUE  Successful  completion 
FALSE  Error  occurred. 

Possible  returns  from  WinGetLastError 

PMERR_DATATYPE_TOO_SMALL 
PMERR_DATATYPE_NOT_UNIQUE 

PMERRARRAYTOOSMALL 
P M E RR_D  AT  ATYPE_ENTR  Y_NOT_N  U M 
PMERR_DAT  ATYPE_ENTRY_NOT_OFF 
P M E R R_DAT  ATYPE_ENTR  Y_BAD_INDEX 
PM  E RR_DAT  ATYPE_ENTR  Y_CTL_M  ISS 
P M E R R_DAT  AT  YPE_ENTR  Y_CTL_BAD 

Remarks 

This  function  has  no  effect  unless  the  RegisterUserMsg  hook,  which  is  invoked  by  this  function,  has 
been  set. 

The  value  to  be  used  should  be  obtained  by  calling  WinAddAtom  with  the  handle  of  the  system  atom 
manager,  and  subtracting  DTYP_ATOM_OFFSET  from  the  result. 

WinAddAtom  is  guaranteed  to  return  values  in  the  range  OxCOOO  to  OxFFFF. 

When  a data  type  is  defined  using  this  function,  a definition  for  the  corresponding  pointer  data  type  is 
automatically  established. 


The  datatype  specified  was  too  small. 

An  attempt  to  register  a datatype  failed  because  it  is  not 
unique. 

The  array  specified  was  too  small. 

The  datatype  entry  specified  was  not  numerical. 

The  datatype  entry  specified  was  not  an  offset. 

An  invalid  datatype  entry  index  was  specified. 

The  datatype  entry  control  was  missing. 

An  invalid  datatype  entry  control  was  specified. 


Chapter  8.  Window  Functions 


8-413 


WinRegisterUserDatatype 
Register  User  Data  Type 


Related  Functions 

• WinBroadcastMsg 

• WinCreateMsgQueue 

• WinDestroyMsgQueue 

• WinDispatchMsg 

• WinGetDIgMsg 

• WinGetMsg 

• WinlnSendMsg 

• WinPeekMsg 

• WinPostMsg 

• WinPostQueueMsg 

• WinQueryMsgPos 

• WinQueryMsgTime 

• WinQueryQueuelnfo 

• WinQueryQueueStatus 

• WinRegisterUserMsg 

• WinSendDIgltemMsg 

• WinSendMsg 

• WinSetClassMsglnterest 

• WinSetMsglnterest 

• WinSetMsgMode 

• WinSetSynchroMode 

• WinWaitMsg 

Example  Code 

This  example  calls  WinRegisterClass  to  register  a class  or  returns  FALSE  if  an  error  occurs. 

fdefine  I NCL_WI NMESSAGEMGR 
fdefine  INCL_WINTYPES 
finclude  <0S2.H> 
fdefine  DTYP_MINE  DTYPJJSER  + 1 

HAB  hab; 

LONG  asTypes[3]  = {DTYP_CHAR, 

0TYP_STRL, 

DTYP_STR32}; 

Wi nReg i s terUserDataT ype ( hab , 

DTYP_MINE, 

3, 

asTypes) ; 
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#define  INCL_WINMESSAGEMGR  /*  Or  use  INCL_WIN  or  INCL_PM.  Also  in  COMMON  section  */ 

BOOL  WinRegisterUserMsg  (HAB  hab,  ULONG  ulMsgld,  LONG  ITypel,  LONG  IDIrl, 

LONG  IType2,  LONG  IDIr2,  LONG  Hyper) 

This  function  registers  a user  message  and  defines  its  parameters. 

Parameters 

hab  (HAB)  - input 

Anchor-block  handle. 

ulMsgld  (ULONG)  - input 
Message  identifier. 

This  must  not  be  less  than  WMUSER,  and  must  not  have  been  defined  previously. 

ITypel  (LONG)  - input 

Data  type  of  message  parameter  1 . 

Valid  data  types  are  listed  below.  For  data  types  that  are  shorter  than  4 bytes,  the  data  must  be 
placed  in  the  least-significant  bytes,  with  the  most  significant  bytes  nullified  (unsigned  data 
types)  or  signed-extended  (signed  data  types). 

DTYP_BIT16  See  USHORT  data  type. 

DTYP_BIT32  See  ULONG  data  type. 

DTYP_BIT8  See  UCHAR  data  type. 

DTYP_BOOL  See  BOOL  data  type. 

DTYP_LONG  See  LONG  data  type. 

DTYP_SHORT  See  SHORT  data  type. 

DTYP_UCHAR  See  UCHAR  data  type. 

DTYPJJLONG  See  ULONG  data  type. 

DTYP_USHORT  See  USHORT  data  type. 

DTYP_P*  A pointer  to  a system  data  type.  Note  that  not  all  of  the  system  data  types  that 

exist  in  the  CPI  are  valid. 

< -DTYP_USER  A pointer  to  a user  data  type.  The  user  data  type  must  have  already  been 
defined  via  WinRegisterUserDatatype. 

IDIrl  (LONG)  - input 

Direction  of  message  parameter  1. 

If  the  message  parameter  is  a pointer,  the  direction  values  listed  below  apply  to  the  contents  of 
the  storage  location  pointed  at,  as  well  as  to  the  message  parameter  itself. 

RUMJN  Input  parameter  (inspected  by  the  recipient  of  the  message,  but  not  altered) 

RUM_OUT  Output  parameter  (altered  by  the  recipient  of  the  message,  without  inspecting  its 
value  first) 

RUMJNOUT  Input/output  parameter  (inspected  by  the  recipient  of  the  message,  and  then 
altered). 

IType2  (LONG)  - input 

Data  type  of  message  parameter  2. 

Seethe  description  of  ITypel. 
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IDir2  (LONG)  - input 

Direction  of  message  parameter  2. 

See  the  description  of  IDirl . 

ITyper  (LONG)  - input 

Data  type  of  message  reply. 

See  the  description  of  ITypel.  The  message  reply  is  always  an  output  parameter. 


Returns 

Success  indicator: 

TRUE  Successful  completion 
FALSE  Error  occurred. 

Possible  returns  from  WinGetLastError 

PMERR  MSGID  TOO_SMALL  The  message  identifier  specified  is  too  small. 

PMERR_DATATYPEJNVALID  An  invalid  datatype  was  specified. 

PMERR_DATATYPE_TOO_LONG  The  datatype  specified  was  too  long. 

Remarks 

This  function  has  no  effect  unless  the  RegisterUserMsg  hook,  which  is  invoked  by  this  function,  has 
been  set. 

It  is  an  error  to  attempt  to  register  the  same  message  identifier  more  than  once  within  a single  OS/2 
process. 

Related  Functions 

• WinBroadcastMsg 

• WinCreateMsgQueue 

• WinDestroyMsgQueue 

• WinDispatchMsg 

• WinGetDIgMsg 

• WinGetMsg 

• WinlnSendMsg 

• WinPeekMsg 

• WinPostMsg 

• WinPostQueueMsg 

• WinQueryMsgPos 

• WinQueryMsgTime 

• WinQueryQueuelnfo 

• WinQueryQueueStatus 

• WinRegisterUserDatatype 

• WinSendDIgltemMsg 

• WinSendMsg 

• WinSetClassMsglnterest 

• WinSetMsglnterest 

• WinSetMsgMode 

• WinSetSynchroMode 

• WinWaitMsg 
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Example  Code 

This  example  uses  the  WinRegisterUserMsg  call  to  register  a user-defined  message  and  define  its 
parameters. 

fdefine  INCL_WINMESSAGEMGR 
fdefine  INCLJIINTYPES 
finclude  <0S2.H> 

fdefine  WM_MY_MESSAGE  WMJJSER  + 11 
HAB  hab; 

WinRegisterUserMessage(hab, 

WM_MY_MESSAGE, 

DTYP_BIT16,  /*  paraml  is  a USHORT  */ 

RUM_IN0UT,  /*  paraml  is  input/output  */ 

DTYP_BIT16,  /*  param2  is  a USHORT  */ 

RUM_IN0UT,  /*  param2  is  input/output  */ 

DTYP_BIT16) ; /*  reply  is  a USHORT  */ 
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#define  INCL_WINHOOKS  /*  Or  use  INCL_WIN  or  INCL_PM  */ 


BOOL  WinReleaseHook  (HAB  hab,  HMQ  hmq,  LONG  IHook,  PFN  pAddress, 
HMODULE  Module) 


This  function  releases  an  application  hook  from  a hook  chain. 

Parameters 

hab  (HAB)  - input 

Anchor-block  handle. 

hmq  (HMQ)  - input 

Handle  of  message  queue  from  which  the  hook  is  to  be  released: 

HMQ_CURRENT  The  hook  is  released  from  the  message  queue  associated  with  the  current 
thread  (calling  thread). 

NULLHANDLE  The  hook  is  released  from  the  system  hook  chain. 

IHook  (LONG)  - input 
Type  of  hook  chain. 

This  must  be  one  of  the  HK_*  values;  see  WinSetHook. 

pAddress  (PFN)  - input 

Address  of  the  hook  routine. 

Module  (HMODULE)  - input 
Module  handle: 

NULLHANDLE  The  hook  procedure  is  in  the  application’s  .EXE  file. 

Module  This  is  the  module  that  contains  the  application  procedure,  as  returned  by  the 

DosLoadModule  or  DosGetModHandle  call. 

Returns 

Success  indicator: 

TRUE  Successful  completion 
FALSE  Error  occurred. 

Possible  returns  from  WinGetLastError 

PMERRINVALIDHMQ 
PMERRPARAMETEROUTOFRANGE 

Related  Functions 

• WinCallMsgFilter 

• WinSetHook 


An  invalid  message-queue  handle  was  specified. 

The  value  of  a parameter  was  not  within  the  defined  valid 
range  for  that  parameter. 
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Example  Code 

This  example  uses  the  WinReleaseHook  call  to  release  a hook  that  records  user-input  messages 
from  the  application  queue. 

fdefine  INCL_WINH00KS 
#i ncl ude  <0S2.H> 

void  RecordHook(HAB  hab,  PQMSG  pqmsg); 
samp() 

{ 

HAB  hab; 

WinSetHook(hab, 

HMQ_CURRENT, 

HKJOURNALRECORD, 

(PFN) RecordHook, 

(HMODULE)O) ; /*  hook  is  into  application  queue.  */ 

WinReleaseHook(hab, 

HMQ_CURRENT, 

HK_JOURNALRECORD, 

(PFN) RecordHook, 

(HMODULE)O);  /*  hook  is  into  application  queue,  */ 


} 

/*  This  hook  records  user-input  messages, 
void  RecordHook(HAB  hab,  PQMSG  pqmsg) 

{ 

/*  ...  */ 

} 


*/ 
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#define  INCL_WINWINDOWMGR  /*  Or  use  INCL_WIN  or  INCL_PM.  Also  in  COMMON  section  */ 


BOOL  WinReleasePS  (HPS  hps) 


This  function  releases  a cache  presentation  space  obtained  using  the  WinGetPS  or  the 
WinGetScreenPS  call. 


Parameters 

hps  (HPS)  - input 

Handle  of  the  cache  presentation  space  to  release. 


Returns 

Success  indicator: 

TRUE  Successful  completion 
FALSE  Error  occurred. 

Remarks 

Only  cache  presentation  spaces  can  be  released  using  this  function,  after  which  the  presentation 
space  is  returned  to  the  cache  to  be  used  again.  The  presentation-space  handle  should  not  be  used 
following  this  call. 


Related  Functions 

• WinBeginPaint 

• WinEnableWindowllpdate 

• WinEndPaint 

• WinExcludeUpdateRegion 

• WinGetClipPS 

• WinGetPS 

• WinGetScreenPS 

• WinlnvalidateRect 

• WinlnvalidateRegion 

• WinlsWindowShowing 

• WinlsWindowVisible 

• WinLockVisRegions 

• WinOpenWindowDC 

• WinQueryllpdateRect 

• WinQueryllpdateRegion 

• WinRealizePalette 

• WinShowWindow 

• WinllpdateWindow 

• WinValidateRect 

• WinValidateRegion 
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Example  Code 

This  example  shows  how  a thread  can  access  a presentation  space,  draw  to  it,  and  release  it. 

fdefine  INCL_DOSSEMAPHORES 
fdefine  INCL_GPIPRIMITIVES 
fdefine  INCL_WINWINDOWMGR 
finclude  <0S2.H> 

HPS  hps; 


hps  = WinGetPS(  hwndClient  ); 


/*  Draw  client  area  */ 


*/ 

*/ 


/*  Release  the  presentation  space  */ 
WinReleasePS(  hps  ); 
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#define  INCL_WINSYS  /*  Or  use  INCL_WIN  or  INCL_PM  7 


BOOL  WinRemovePresParam  (HWND  hwnd,  ULONG  IdAttrType) 


This  function  removes  a presentation  parameter  associated  with  the  window  hwnd. 


Parameters 

hwnd  (HWND)  - input 
Window  handle. 

IdAttrType  (ULONG)  - input 
Attribute  type  identity. 

The  type  of  the  presentation  parameter  attribute  that  is  to  be  removed. 


Returns 

Success  indicator: 

TRUE  Successful  completion 
FALSE  Error  occurred. 

Possible  returns  from  WinGetLastError 

PMERRINVALIDHWND  An  invalid  window  handle  was  specified. 

Remarks 

See  also  WinSetPresParam  and  WinQueryPresParam. 


Related  Functions 

• WinDrawBitmap 

• WinDrawBorder 

• WinDrawPointer 

• WinDrawText 

• WinFillRect 

• WinGetSysBitmap 

• WinlnvertRect 

• WinQueryPresParam 

• WinScrollWindow 

• WinSetPresParam 
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Example  Code 

This  example  removes  the  disable-foreground  attribute  after  querying  to  ensure  that  the  referenced 
window  has  this  attribute  defined. 


fdefine  INCL_WINSYS  /*  System  values  */ 

finclude  <os2.h> 

HWND  hwnd;  /*  window  handle  */ 

ULONG  AttrFound;  /*  attributes  found  */ 

ULONG  AttrValue[32];  /*  attribute  value  */ 

ULONG  cbRetLen;  /*  length  of  returned  value  */ 


WinRemovePresParam(hwnd,  PP_DISABLEDFOREGROUNDCOLORINDEX); 
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#define  INCL_WINSWITCHLIST  /*  Or  use  INCL_WIN  or  INCL_PM.  Also  in  COMMON  section  */ 


USHORT  WinRemoveSwitchEntry  (HSWITCH  hswItchSwitch) 


This  function  removes  a specified  entry  from  the  Window  List. 

Parameters 

hswItchSwitch  (HSWITCH)  - input 

Switch-list  (Window  List)  entry  handle. 


Returns 

Success  indicator: 

0 Successful  completion 

Other  Error  occurred. 

Possible  returns  from  WinGetLastError 

PMERRJNVALID  SWITCH  HANDLE  An  invalid  Window  List  entry  handle  was  specified. 

PMERR_INVALID_WINDOW  The  window  specified  with  a Window  List  function  is  not  a 

valid  frame  window. 


Remarks 

An  application  that  uses  the  operating  system  effectively  should,  at  least,  add  its  main  window  to  the 
Window  List  when  it  starts,  and  remove  it  from  the  Window  List  when  it  stops. 

Window  List  entries  for  non-OS/2  applications  cannot  be  removed  using  this  function.  These  entries 
are  removed  automatically  by  the  system  when  the  session  they  occupy  terminates. 

Note:  This  function  and  the  WinCreateSwitchEntry  and  WinAddSwitchEntry  functions  are  not 
required  if  the  main  window  is  created  with  the  frame  style  FCF_TASKLIST  or 
FCF_STANDARD,  as  these  styles  automatically  update  the  Window  List  when  the  main  window 
is  created,  destroyed,  or  its  title  changes. 


Related  Functions 

• WinAddSwitchEntry 

• WinChangeSwitchEntry 

• WinCreateSwitchEntry 

• WinQuerySessionTitle 

• WinQuerySwitchEntry 

• WinQuerySwitchHandle 

• WinQuerySwitchList 

• WinQueryTaskSizePos 

• WinQueryTaskTitle 

• WinSwitchToProgram 
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Example  Code 

This  example  calls  WinQuerySwitchHandle  to  get  the  Task  List  handle  of  a frame  window,  and  then 
calls  WinRemoveSwitchEntry  to  remove  it. 

Idefine  INCL_WINSWITCHLIST 
finclude  <0S2.H> 

HAB  hab; 

HWND  hwndFrame; 

HSWITCH  hswitch; 

SWCNTRL  swctl ; 

hswitch  = WinQuerySwitchHandle(hwndFrame,  0); 

WinRemoveSwi tchEntry( hswitch) ; 
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#define  INCL_WINWORKPLACE 


BOOL  WinReplaceObjectClass  (PSZ  pszOidCiassName,  PSZ  pszNewClassName, 

BOOL  fReplace) 


The  WinReplaceObjectClass  function  replaces  a registered  class  with  another  registered  class.  If 
fReplace  is  FALSE,  pszOidCiassName  will  revert  back  to  its  original  definition. 


Parameters 

pszOidCiassName  (PSZ)  - input 

A pointer  to  a zero-terminated  string  which  contains  the  name  of  the  object  class  being  replaced 
by  pszNewClassName  in  the  workplace. 

pszNewClassName  (PSZ)  - input 

A pointer  to  a zero-terminated  string  which  contains  the  name  of  the  object  class  replacing  the 
pszOidCiassName  class. 

fReplace  (BOOL)  - input 

TRUE  Replace  the  function  of  class  pszOidCiassName  with  the  function  of  the  class 
pszNewClassName. 

FALSE  Undo  the  replacement  of  the  pszOidCiassName  with  pszNewClassName  by  restoring 
the  pszOidCiassName  back  to  its  original  functionality. 

Returns 

Success  indicator: 

TRUE  Successful  completion 
FALSE  Error  occurred. 

Remarks 

The  class  specified  by  pszNewClassName  must  be  a descendant  of  the  class  specified  by 
pszOidCiassName,  otherwise  an  error  will  be  returned.  Replacing  an  object  is  useful  if  it  is  desired 
to  modify  the  behavior  of  objects  which  are  instances  of  the  class  pszOidCiassName  and  which  are 
not  aware  of  the  class  pszNewClassName. 


Related  Functions 

• WinCreateObject 

• WinDeregisterObjectClass 

• WinRegisterObjectClass 
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#define  INCLWINMESSAGEMGR 


ULONG  WinRequestMutexSem  (HMTX  hmtx,  ULONG  ulTImeout) 


WinRequestMutexSem  requests  ownership  of  a mutex  semaphore  or  waits  for  a Presentation 
Manager  message. 


Parameters 

hmtx  (HMTX)  - input 

The  handle  of  the  mutex  semaphore  to  request. 
ulTImeout  (ULONG)  - input 

The  time-out  in  milliseconds.  This  is  the  maximum  amount  of  time  the  user  wants  to  allow  the 
thread  to  be  blocked. 

This  parameter  can  also  have  the  following  values: 

Value  Definition 

0 (SEM_IMMEDIATE_RETURN)  WinRequestMutexSem  returns  immediately  without 

blocking  the  calling  thread. 

-1  (SEM_INDEFINITE_WAIT)  WinRequestMutexSem  blocks  the  calling  thread 

indefinitely. 

Returns 

Return  Code. 

WinRequestMutexSem  returns  the  following  values: 

0 NO_ERROR 

6 ERROR_INVALID_HANDLE 

95  ERRORJNTERRUPT 

103  ERROR_TOO_MANY_SEM_REQUESTS 

105  ERROR_SEM_OWNER_DIED 

640  ERROR_TIMEOUT 

Remarks 

WinRequestMutexSem  is  similar  to  DosRequestMutexSem  and  requests  ownership  of  a mutex 
semaphore  or  waits  for  a window  message  sent  by  the  WinSendMsg  function  from  another  thread  to 
be  received. 

This  function  can  be  called  by  any  thread  in  the  process  that  created  the  semaphore.  Threads  in 
other  processes  can  also  call  this  function,  but  they  must  first  gain  access  to  the  semaphore  by 
issuing  DosOpenMutexSem. 

Since  the  processing  of  a window  message  may  take  longer  than  the  value  specified  by  the 
ulTimeout  parameter,  this  function  may  not  return  within  the  time  specified  by  that  value. 
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WinRequestMutexSem  - 
Request  Mutex  Semaphore 


Related  Functions 

• WinSendMsg 

• WinPostMsg 

Example  Code 

This  example  requests  ownership  of  a mutex  semaphore.  Assume  that  the  handle  of  the  semaphore 
has  been  placed  Into  hmtx  already. 

ulTimeout  Is  the  number  of  milliseconds  that  the  calling  thread  will  wait  for  ownership  of  the  mutex 
semaphore.  If  the  specified  mutex  semaphore  is  not  released  during  this  time  interval,  the  calling 
thread  does  not  receive  ownership  of  it. 

#def ine  INCL_DOSSEMAPHORES  /*  Semaphore  values  */ 
fdefine  INCL.WINMESSAGEMGR 
finclude  <os2.h> 
finclude  <stdio.h> 

#ifndef  ERRORJTMEOUT 

fdefine  ERRORJTMEOUT  640 
fdefine.  ERRORJNTERRUPT  95 
fendif 

HMTX  hmtx;  /*  Mutex  semaphore  handle  */ 

ULONG  ulTimeout;  /*  Number  of  milliseconds  to  wait  */ 

ULONG  rc;  /*  Return  code  */ 

ulTimeout  = 60000;  /*  Wait  for  a maximum  of  1 minute  */ 

rc  = WinRequestMutexSem(hmtx,  ulTimeout); 

if  (rc  = ERROR JIMEOUT) 

{ 

printf( “WinRequestMutexSem  call  timed  out"); 
return; 

} 

if  (rc  = ERRORJNTERRUPT) 

{ 

printfO'WinRequestMutexSem  call  was  interrupted"); 
return; 

} 

if  (rc  !=  0) 

{ 

printf( "WinRequestMutexSem  error:  return  code  = %ld",  rc); 
return; 

} 
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WinRestoreWindowPos  - 
Restore  Window  Position 


#define  INCL_WINWORKPLACE 


BOOL  WinRestoreWindowPos  (PSZ  pszAppName,  PSZ  pszKeyName,  HWND  hwnd) 


The  WinRestoreWindowPos  function  will  restore  the  size  and  position  of  the  window  specified  by 
hwnd  to  the  state  it  was  in  when  WinStoreWindowPos  was  last  called  with  the  same  pszAppName 
and  pszKeyName. 

Parameters 

pszAppName  (PSZ)  - input 

A pointer  to  a zero-terminated  string  which  contains  the  application  name. 
pszKeyName  (PSZ)  - input 

A pointer  to  a zero-terminated  string  which  contains  the  key  name, 
hwnd  (HWND)  - input 

Window  handle  of  the  window  to  restore. 

Returns 

Success  indicator: 

TRUE  Successful  completion 
FALSE  Error  occurred. 

Remarks 

This  function  will  also  restore  presentation  parameters  which  were  saved  by  a previous  call  to 
WinStoreWindowPos. 

Related  Functions 

• WinStoreWindowPos 
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WinSaveWindowPos  - 
Save  Window  Position 


#define  INCL_WINFRAMEMGR  /*  Or  use  INCL_WIN  or  INCL_PM  */ 


BOOL  WinSaveWindowPos  (HSVWP  hsvwp,  PSWP  aswpaswp,  ULONG  ccswp) 


This  function  associates  an  array  of  SWP  structures  with  the  process  of  repositioning  a frame 
window. 

Parameters 

hsvwp  (HSVWP)  - input 

Identifier  of  the  frame  window  repositioning  process. 

This  handle  is  provided  in  the  second  parameter  of  the  WMADJUSTFRAMEPOS  message. 

aswpaswp  (PSWP)  - input 
Array  of  SWP  structures. 

ccswp  (ULONG)  - input 

Count  of  SWP  structures. 


Returns 

Success  indicator: 

TRUE  Successful  completion 
FALSE  Error  occurred. 

Remarks 

This  function  is  used  only  during  the  processing  of  the  WM  ADJUSTFRAMEPOS  message. 


Related  Functions 

• WinGetMinPosition 

• WinQueryActiveWindow 

• WinQueryWindowPos 

• WinSetActiveWindow 

• WinSetMultWindowPos 

• WinSetWindowPos 

Related  Messages 

• WM_ADJUSTFRAMEPOS 
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WinSaveWindowPos  - 
Save  Window  Position 


Example  Code 

This  example  shows  how  the  repositioning  of  a window  is  recorded  in  SWP  structures  with  the 
WinSaveWindowPos  call. 

fdefine  INCLJIINFRAMEMGR 
finclude  <0S2.H> 
fdefine  COUNT  10 
HSAVEWP  hsvwp; 

SWP  aswp [COUNT]; 

ULONG  msg; 

switch(msg){ 

case  WM_ADJUSTFRAMEPOS: 

Wi nSaveWi ndowPos (hsvwp , aswp , COUNT) ; 

} 
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WinScrollWindow 
Scroll  Window 


#define  INCL_WINWINDOWMGR  /*  Or  use  INCL_WIN  or  INCL_PM.  Also  in  COMMON  section  7 


LONG  WinScrollWindow  (HWND  hwnd,  LONG  IDx,  LONG  IDy,  PRECTL  prcIScroll, 

PRECTL  prcIClip,  HRGN  hrgnUpdateRgn,  PRECTL  prclUpdate, 
ULONG  flOptlons) 


This  function  scrolls  the  contents  of  a window  rectangle. 


Parameters 

hwnd  (HWND)  - input 
Window  handle. 

IDx  (LONG)  - input 

Amount  of  horizontal  scroll  to  the  right  (in  device  units). 

IDy  (LONG)  - input 

Amount  of  vertical  scroll  upward  (in  device  units). 

prcIScroll  (PRECTL)  - input 
Scroll  rectangle. 

If  this  is  NULL,  the  entire  window  is  scrolled. 

Note:  The  value  of  each  field  in  this  structure  must  be  in  the  range  —32  768  through  32  767.  The 
data  type  WRECT  may  also  be  used,  if  supported  by  the  language. 

prcIClip  (PRECTL)  - input 
Clip  rectangle. 

If  not  NULL,  this  defines  a clip  rectangle  that  clips  the  destination  of  the  scroll. 

hrgnUpdateRgn  (HRGN)  - input 
Update  region. 

If  not  NULLHANDLE,  this  contains  the  region  uncovered  by  the  scroll  when  returned. 

prclUpdate  (PRECTL)  - input/output 
Update  rectangle. 

If  not  NULL,  this  contains  the  bounding  rectangle  of  the  invalid  bits  uncovered  by  the  scroll  when 
returned. 

flOptlons  (ULONG)  - input 
Scroll  options. 

SW_SCROLLCHILDREN 

Unless  this  is  set,  child  windows  are  not  scrolled.  If  this  is  set,  and  prcIScroll  is  NULL,  all  the 
child  windows  are  scrolled  by  IDx  and  IDy  units.  If  prcIScroll  is  not  NULL,  only  those  child 
windows  that  intersect  prcIScroll  are  scrolled. 

SWJNVALIDATERGN 

The  invalid  region  created  as  a result  of  the  scroll  is  added  to  the  update  regions  of  those 
windows  affected.  This  may  result  in  sending  WM  PAINT  messages  to  CS_SYNCPAINT 
windows  before  the  call  returns. 
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WinScrol  I Window  - 
Scroll  Window 


Returns 

Complexity  of  resulting  region/error  indicator: 
RGN_NULL  NULL  rectangle  invalid 

RGN_RECT  Simple  rectangle  invalid 

RGN_COMPLEX  Complex  rectangle  invalid 
RGN  ERROR  Error. 


Possible  returns  from  WinGetLastError 

PMERR  INVALID  HWND  An  invalid  window  handle  was  specified. 

PMERR_INVALID_FLAG  An  invalid  bit  was  set  for  a parameter.  Use  constants 

defined  by  PM  for  options,  and  do  not  set  any  reserved 
bits. 

PMERR_HRGN_BUSY  An  internal  region  busy  error  was  detected.  The  region 

was  locked  by  one  thread  during  an  attempt  to  access  it 
from  another  thread. 


Remarks 

This  function  scrolls  the  contents  of  a rectangle  defined  by  prcIScroll  in  the  window  hwnd,  by  IDx 
units  horizontally  and  IDy  units  vertically.  All  coordinates  must  be  in  device  units. 

Clipping  takes  place  on  the  final  image  of  the  scroliing.  Even  if  the  scroll  rectangle  lies  outside  the 
clip  rectangle,  these  bits  are  scrolled,  if  their  destination  lies  within  the  intersection  of  the  clip 
rectangle  and  the  destination  rectangle. 

This  function  returns  an  RGN_*  value,  indicating  the  type  of  invalid  region  created  by  the  scroll  as 
returned  by  GpiCombineRegion.  RGN_ERROR  is  returned  if  hwnd  iS  invalid. 

Note:  If  hwnd  has  style  WS_CLIPCHILDREN,  portions  of  any  child  window  within  the  scroll  area  are 
scrolled.  In  this  instance,  this  function  must  be  called  with  flOptions  SW_SCROLLCHILDREN. 

This  is  the  only  function  that  can  be  used  by  a thread  to  move  bits  within  its  own  window,  because  of 
the  critical  section  nature  of  window  update  regions. 

Scrolling  is  fastest  without  SW_SCROLLCHILDREN  and  SWJNVALIDATERGN.  When  scrolling  needs 
to  be  repeated  quickly,  do  not  include  the  SWJNVALIDATERGN  flag  and  repaint  the  invalid  area  if  the 
invalid  region  is  rectangular,  otherwise  invalidate  and  update. 

If  the  scrolling  is  infrequent,  include  the  SWJNVALIDATERGN  flag.  This  function  invalidates  and 
updates  synchronous-paint  windows  automatically  before  returning. 

The  cursor  and  the  track  rectangle  are  scrolled  when  they  intersect  with  the  scrolled  region.  Any 
part  of  the  window’s  initial  update  region  that  intersects  the  scrolled  region  is  also  offset. 


Related  Functions 

• WinDrawBitmap 

• WinDrawBorder 

• WinDrawPointer 

• WinDrawText 

• WinFillRect 

• WinGetSysBitmap 

• WinlnvertRect 

• WinQueryPresParam 

• WinRemovePresParam 

• WinSetPresParam 
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WinScrollWindow 
Scroll  Window 


Related  Messages 

• WM_ERASEWINDOW 

• WM  PAINT 


Example  Code 

This  example  shows  a very  small  part  of  the  processing  that  must  be  done  for  a WM  VSCROLL 
message,  which  will  be  sent  when  a vertical  scroll  bar  has  a significant  event  to  notify  its  owner. 

fdefine  INCL_WINSCROLLBARS 
#define  INCL_WINWINDOWMGR 
finclude  <0S2.H> 
fdefine  COUNT  10 
HWND  hwndClient; 

MPARAM  mp2 ; 

ULONG  msg; 

switch(msg) 

{ 

case  WM_VSCROLL: 
switch  ( SH0RT2FR0MMP (mp2) ) 


case  SB_LINEUP:  /*  Sent  if  the  operator  */ 

/*  clicks  on  the  up  arrow  */ 

/*  of  the  scroll  bar,  or  */ 

/*  presses  the  VKJJP  */ 

/*  key.  */ 

Wi nScrol 1 Wi ndow(hwndCl i ent , 

0, 

(LONG)20,  /*  vertical  scroll  */ 

(PRECTL)NULL, 

(PRECTL)NULL, 

(HRGN)NULLHANDLE, 

(PRECTL)NULL, 

0); 

break; 


break; 

} 
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WinSendDIgltemMsg  - 
Send  Message  to  Dialog  Item 


#define  INCL_WINDIALOGS  /*  Or  use  INCL_WIN  or  INCL_PM  */ 


M RESULT  WinSendDIgltemMsg  (HWND  hwndDIg,  ULONG  Idltem,  ULONG  ulMsgld, 

MPARAM  mpParaml , MPARAM  mpParam2) 


This  function  sends  a message  to  the  dialog  item  defined  by  idltem  in  the  dialog  window  specified  by 
hwndDIg. 


Parameters 

hwndDIg  (HWND)  - input 
Parent-window  handle. 

Idltem  (ULONG)  - input 

Identity  of  the  child  window. 

ulMsgld  (ULONG)  - input 
Message  identity. 

mpParaml  (MPARAM)  - input 
Message  parameter  1. 

mpParam2  (MPARAM)  - input 
Message  parameter  2. 


Returns 

Message-return  data. 

Possible  returns  from  WinGetLastError 

PMERR  INVALID  HWND  An  invalid  window  handle  was  specified. 

Remarks 

This  function  is  equivalent  to  the  WinSendMsg  function,  in  which  the  receiving  window  procedure  is 
specified  by  means  of  the  item  identity  of  the  child  window  and  parent-window  handle. 

It  does  not  return  until  the  message  has  been  processed  by  the  dialog  item,  whose  return  value  is 
returned  in  mresReply. 

The  call  is  equivalent  to: 

WinSendMsg  (WinWindowFromID(hwndDlg,  idltem),  msgid,  paraml,  param2,  reply); 

This  function  is  valid  for  any  window  with  children;  however,  it  is  typically  used  for  dialog  items  in  a 
dialog  window. 


Related  Functions 

• WinBroadcastMsg 

• WinCreateMsgQueue 

• WinDestroyMsgQueue 

• WinDispatchMsg 

• WinGetDIgMsg 

• WinGetMsg 

• WinlnSendMsg 

• WinPeekMsg 

• WinPostMsg 
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WinSendDIgltemMsg  - 
Send  Message  to  Dialog  Item 


• WinPostQueueMsg 

• WinQueryMsgPos 

• WinQueryMsgTime 

• WinQueryQueuelnfo 

• WinQueryQueueStatus 

• WinRegisterllserDatatype 

• WinRegisterUserMsg 

• WinSendMsg 

• WinSetClassMsglnterest 

• WinSetMsglnterest 

• WinSetMsgMode 

• WinSetSynchroMode 

• WinWaitMsg 

Example  Code 

This  example  processes  an  application-defined  message  (IDM_SHOW)  and  sets  a check  mark  next  to 
the  selected  item. 

Idefine  INCL_WIN 
Idefine  INCLJIINDIALOGS 
linclude  <0S2.H> 

Idefine  IDM_SH0W  902 

HWND  hwndFrame; 

ULONG  msg; 

MPARAM  mpl; 

/*  Inside  client  procedure.  */ 

switch (msg) 

{ 

case  WM_COMMAND: 

/*  The  user  has  chosen  a menu  item.  Process  the  selection  */ 

/*  accordingly.  */ 

switch  ( SH0RT1FR0MMP(  mpl  ) ) 

{ 


case  IDM_SH0W: 

WinSendDlgItemMsg(hwndFrame,  (ULONG)  FID_MENU, 
(ULONG)  MM_SETITEMATTR, 
MPFR0M2SH0RT(IDM_SH0W,  TRUE), 
MPFR0M2SH0RT(MIA_CHECKED,MIA_CHECKED) ) ; 

break; 

} 

break; 

} 


8-436  PM  Programming  Reference 


WinSendMsg  - 
Send  Message 


#define  INCL  WINMESSAGEMGR  /*  Or  use  INCL_WIN  or  INCL_PM.  Also  in  COMMON  section  7 


MRESULT  WinSendMsg  (HWND  hwnd,  ULONG  ulMsgld,  MPARAM  mpParaml, 
M PAR  AM  mpParam2) 


This  function  sends  a message  with  identity  ulMsgid  to  hwnd,  passing  mpParaml  and  mpParam2  as 
the  parameters  to  the  window. 


Parameters 

hwnd  (HWND)  - input 
Window  handle. 

ulMsgld  (ULONG)  - input 
Message  identity. 

mpParaml  (MPARAM)  - input 
Parameter  1 . 

mpParam2  (MPARAM)  - input 
Parameter  2. 


Returns 

Message-return  data. 

Possible  returns  from  WinGetLastError 

PMERR  INVALID  HWND  An  invalid  window  handle  was  specified. 

PMERR_WINDOW_NOT_LOCKED  The  window  specified  in  WinSendMsg  was  not  locked. 

Remarks 

mresReply  is  the  value  returned  by  the  window  procedure  that  is  invoked.  For  standard  window 
classes,  the  values  of  mresReply  are  documented  with  the  message  definitions. 

This  function  does  not  complete  until  the  message  has  been  processed  by  the  window  procedure 
whose  return  value  is  returned  in  mresReply. 

If  the  window  receiving  the  message  belongs  to  the  same  thread,  the  window  function  is  called 
immediately  as  a subroutine.  If  the  window  is  of  another  thread  or  process,  the  operating  system 
switches  to  the  appropriate  thread  that  enters  the  necessary  window  procedure  recursively.  The 
message  is  not  placed  in  the  queue  of  the  destination  thread. 
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WinSendMsg  - 
Send  Message 


Related  Functions 

• WinBroadcastMsg 

• WinCreateMsgQueue 

• WinDestroyMsgQueue 

• WinDispatchMsg 

• WinGetDIgMsg 

• WinGetMsg 

• WinlnSendMsg 

• WinPeekMsg 

• WinPostMsg 

• WinPostQueueMsg 

• WinQueryMsgPos 

• WinQueryMsgTime 

• WinQueryQueuelnfo 

• WinQueryQueueStatus 

• WinRegisterUserDatatype 

• WinRegisterllserMsg 

• WinSendDIgltemMsg 

• WinSetClassMsglnterest 

• WinSetMsglnterest 

• WinSetMsgMode 

• WinSetSynchroMode 

• WinWaitMsg 

Example  Code 

This  example  gets  the  window  handle  of  the  system  menu  and  calls  WinSendMsg  to  send  a message 
to  disable  the  Close  menu  item. 

fdefine  INCL_WINMENUS 
fdefine  INCL.WINMESSAGEMGR 
fdefine  INCL_WINFRAMEMGR 
finclude  <0S2.H> 

HWND  hwndDlg; 

HWND  hwndSysMenu; 

hwndSysMenu  = WinWindowFromID( hwndDlg,  FID_SYSMENU); 

Wi nSendMs g ( hwndSysMenu , MM_SETITEMATTR , 

MPFR0M2SH0RT(SC_CL0SE,  TRUE), 

MPFR0M2SH0RT(MIA_DISABLED,  MI A_DISABLED) ) ; 
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WinSetAccelTable  - 
Set  Accelerator  Table 


#define  INCL_WINACCELERATORS  /*  Or  use  INCL_WIN  or  INCL_PM  */ 


BOOL  WinSetAccelTable  (HAB  hab,  HACCEL  haccelAccel,  HWND  hwndFrame) 


This  function  sets  the  window-accelerator,  or  queue-accelerator  table. 


Parameters 

hab  (HAB)  - input 

Anchor-block  handle. 

haccelAccel  (HACCEL)  - input 
Accelerator-table  handle: 

NULLHANDLE  Remove  any  accelerator  table  in  effect  for  the  window  or  the  queue 

Other  Accelerator-table  handle. 

hwndFrame  (HWND)  - input 
Frame-window  handle: 

NULLHANDLE  Set  the  queue-accelerator  table 
Other  Set  the  window-accelerator  table. 

Returns 

Success  indicator: 

TRUE  Successful  completion 
FALSE  Error  occurred. 

Possible  returns  from  WinGetLastError 

PMERRINVALIDHWND 
P M ER  R_IN  V ALIDH  ACCEL 

Related  Functions 

• WinCopyAccelTable 

• WinCreateAccelTable 

• WinDestroyAccelTable 

• WinLoadAccelTable 

• WinQueryAccelTable 

• WinTranslateAccel 


An  invalid  window  handle  was  specified. 

An  invalid  accelerator-table  handle  was  specified. 


Chapter  8.  Window  Functions  8-439 


W inSet AccelTable  - 
Set  Accelerator  Table 


Example  Code 

This  example  uses  the  WinSetAccelTable  call  to  remove  any  accelerator  table  in  effect  for  the 
window. 

Idefine  INCL_WIN 
linclude  <0S2.H> 

HWND  hwndFrame,  hwndClient; 

HAB  hab; 

HACCEL  haccel; 


hwndFrame  = WinQueryWindow(hwndClient, 

QW_PARENT);  /*  get  handle  of  parent,  */ 
/*  which  is  frame  window.  */ 


Wi nSetAccel Tabl e (hab, 

(HACCEL) 0,  /*  remove  any  accelerator  table  in  */ 
/*  effect.  */ 

hwndFrame) ; 
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WinSetActiveWindow  - 
Set  Active  Window 


#define  INCL_WINWINDOWMGR  /*  Or  use  INCL_WIN  or  INCL_PM.  Also  in  COMMON  section  7 


BOOL  WinSetActiveWindow  (HWND  hwndDeskTop,  HWND  hwnd) 


This  function  makes  the  frame  window  the  active  window. 

Parameters 

hwndDeskTop  (HWND)  - input 
Desktop-wi  ndow  handle: 

HWND_DESKTOP  The  desktop-window  handle 

Other  Specified  desktop-window  handle. 

hwnd  (HWND)  - input 
Window  handle. 

hwnd  is  either  the  frame  window  or  its  child.  If  it  is  a child,  the  parent  frame  window  will 
become  the  active  window. 

Returns 

Active-window-set  indicator: 

TRUE  Active  window  is  set 
FALSE  Active  window  is  not  set. 

Possible  returns  from  WinGetLastError 

PMERRJNVALID  HWND  An  invalid  window  handle  was  specified. 

Remarks 

This  function  is  equivalent  to  the  WinFocusChange  function  in  which  the  fIFocusChange  parameter  is 
set  to  FC_SETACTIVEFOCUS. 

Related  Functions 

• WinGetMinPosition 

• WinQueryActiveWindow 

• WinQueryWindowPos 

”*  • WinSaveWindowPos 

• WinSetMultWindowPos 

• WinSetWindowPos 

Example  Code 

This  example  uses  the  WinSetActiveWindow  call  to  make  the  main  window  the  active  window. 

Idefine  INCL_WINWINDOWMGR 
finclude  <0S2.H> 

HWND  hwnd; 

WinSetActiveWindow(HWND_DESKTOP,hwnd); 
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WinSetCapture 
Set  Capture 


#define  INCL_WININPUT  /*  Or  use  INCL_WIN  or  INCL_PM  */ 


BOOL  WinSetCapture  (HWND  hwndDesktop,  HWND  hwnd) 


This  function  captures  all  pointing  device  messages. 


Parameters 

hwndDesktop  (HWNO)  - input 

Desktop-window  handle,  or  HWND_DESKTOP. 

hwnd  (HWND)  - input 

Handle  of  the  window  that  is  to  receive  all  pointing  device  messages. 

hwnd  can  take  the  special  value  HWND_THREADCAPTURE  to  capture  the  pointing  device  to  the 
current  thread  rather  than  to  a particular  window.  HWND_THREADCAPTURE  is  unique  among 
window  handles. 

If  hwnd  is  NULLHANDLE,  pointing  device  capture  is  released. 


Returns 

Success  indicator: 

TRUE  Successful  completion. 

FALSE  Error  occurred.  If  the  pointing  device  has  already  been  captured  by  another  thread  or 
window,  the  call  fails.  This  is  to  prevent  applications  from  removing  the  capture  from 
other  windows  or  threads. 

Possible  returns  from  WinGetLastError 

PMERR  INVALID  HWND  An  invalid  window  handle  was  specified. 

Remarks 

This  function  assigns  the  pointing  device  capture  to  hwnd. 

With  the  pointing  device  capture  set  to  a window,  all  pointing  device  input  is  directed  to  that  window, 
regardless  of  whether  the  pointing  device  pointer  is  over  that  window. 

When  this  function  ( hwndDesktop , NULLHANDLE)  is  called  to  release  the  pointing  device  capture,  a 
WM  MOUSEMOVE  message  is  posted  regardless  of  whether  the  pointing  device  pointer  has  actually 
moved.  This  ensures  that  the  window  below  the  pointing  device,  at  that  time,  is  able  to  change 
features,  such  as  the  shape  of  the  pointing  device  pointer. 

If  this  function  ( hwndDesktop , HWND  THREADCAPTURE)  is  called,  the  pointing  device  is  captured  to 
the  current  thread.  Pointing  device  QMSGs  processed  in  this  manner  have  NULLHANDLE  window 
handles,  and  the  pointing  device  coordinates  are  relative  to  the  screen. 

This  function  returns  an  unlocked  window  handle. 

It  must  only  be  called  while  processing  pointing  device  or  keyboard  input.  A message  box  or  dialog 
box  must  not  be  created  while  the  pointing  device  is  captured. 
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Set  Capture 


Related  Functions 

• WinQueryCapture 

Related  Messages 

• WM_MOUSEMOVE 

Example  Code 

This  example  uses  the  WinSetCapture  call  to  capture  the  mouse  until  the  button  is  released.  The  user 
has  selected  a specific  object  with  mouse  button  2. 

fdefine  INCL_WININPUT 
finclude  <0S2.H> 

HWND  hwnd; 

USHORT  msg; 

Wi nSetCapture ( hwnd , HWND_DES  KTOP) ; 
switch  (msg)  { 
case  WM_BUTT0N2D0WN: 

j *********** ******** ******** ******** ******************************** j 

/*  An  object  has  been  picked.  Set  the  mouse  capture  until  */ 

/*  a 'button  up'  message  is  detected.  */ 

y*******************************************************************  j 

if  (hwnd  !=  WinQueryFocus(HWND_DESKTOP)){ 

Wi nSetFocus (HWND_DESKTOP,  hwnd) ; 

} 

Wi nSetCapture (HWND_DESKTOP,  hwnd) ; 
break; 

} 
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WinSetClassMsglnterest  - 
Set  Class  Message  Interest 


#define  INCLJ/VINMESSAGEMGR  /*  Or  use  INCLWIN  or  INCL_PM  */ 


BOOL  WinSetClassMsglnterest  (HAB  hab,  PSZ  pszClassName,  ULONG  ulMsgClass, 

LONG  IControl) 


This  function  sets  the  message  interest  of  a window  class. 

Parameters 

hab  (HAB)  - input 

Anchor-block  handle. 

pszClassName  (PSZ)  - input 
Window-class  name. 

ulMsgClass  (ULONG)  - input 

Message  class  to  have  interest  level  set: 

msgld  A single  message  identity  (for  example,  WMSHOW) 

SMIMALL  All  messages  (except  for  WM_QUIT  if  IControl  is  SMI_AUTODISPATCH  or 
SMI_NOINTEREST). 

IControl  (LONG)  - input 

Interest  identifier  for  the  message  class: 

SMIJNTEREST  Interested  in  the  message,  or  messages 

SMI_NOINTEREST  Not  interested  in  the  message,  or  messages 

SMI_AUTODISPATCH  Interested  in  the  message  or  messages,  but  they  are  to  be  automatically 
dispatched  to  the  window  procedure. 
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Returns 

Interest-changed  indicator: 

TRUE  Interest  successfully  changed 
FALSE  Interest  not  successfully  changed. 

Possible  returns  from  WinGetLastError 

PMERR  INVALID  HWND  An  invalid  window  handle  was  specified. 


Remarks 

This  function  has  no  effect  unless  the  MsgCtIHook  hook,  which  is  invoked  by  this  function,  has  been 
set.  The  interest  for  WM_QUIT  cannot  be  set  to  SMIAUTODISPATCH  using  SMIM_ALL,  because 
WMQUIT  is  the  normal  means  of  terminating  an  application.  It  can  be  set  specifically,  if  required. 


Related  Functions 

• WinBroadcastMsg 

• WinCreateMsgQueue 

• WinDestroyMsgQueue 

• WinDispatchMsg 

• WinGetDIgMsg 

• WinGetMsg 

• WinlnSendMsg 

• WinPeekMsg 

• WinPostMsg 

• WinPostQueueMsg 

• WinQueryMsgPos 

• WinQueryMsgTime 

• WinQueryQueuelnfo 

• WinQueryQueueStatus 

• WinRegisterllserDatatype 

• WinRegisterllserMsg 

• WinSendDIgltemMsg 

• WinSendMsg 

• WinSetMsglnterest 

• WinSetMsgMode 

• WinSetSynchroMode 

• WinWaitMsg 


Chapter  8.  Window  Functions 


8-445 


WinSetClassMsglnterest  - 
Set  Class  Message  Interest 


Example  Code 

This  example  uses  the  WinSetClassMsglnterest  call  to  set  the  message  interest  of  window  class 
WC_MENU.  It  allows  one  to  process  the  messages  of  this  window  class  in  the  MsgControlHook 
procedure. 

fdefine  I NCL_WI NMESSAGEMGR 
fdefine  INCL_WINH00KS 

fdefine  INCL_WINMENUS  /*  for  WC_MENU  parameter  definition.  */ 

finclude  <0S2.H> 

main() 

{ 

/*  Hook  Procedure  Prototype  */ 

BOOL  MsgControlHook(HAB  hab.LONG  idContext,  /*  this  hook  can  */ 

HWND  hwnd,  PSZ  pszClassname,  /*  be  given  any  */ 

ULONG  ulMsgclass,  /*  name.  */ 

LONG  idControl,  PBOOL  fSuccess); 

HWND  hwnd; 

HAB  hab; 

BOOL  fSuccess; 


/*  This  function  passes  the  hook  procedure  address  to  the  system.  */ 

WinSetHook(hab, 

(HMQ)0, 

MCHK_CLASSMSGINTEREST, 

(PFN)MsgControlHook, 

(HMODULE)O);  /*  hook  is  into  application  queue.  */ 


/* 

This  function  sets  the  message  interest  of  a window  class. 

*/ 

Wi nSetCl assMsglnterest (hab, 

WC_MENU,  /*  menu  window  class.  */ 

SMIM_ALL,  /*  set  interest  level  for  all  */ 

/*  messages.  */ 

SMI_AUTODISPATCH) ; /*  interested  in  the  */ 

/*  messages,  but  they  are  to  */ 

/*  be  automatically  dispatched  */ 

/*  to  the  window  procedure.  */ 

} 

/* 

This  hook  allows  the  call  which  determine  the  flow  of  messages  to  be 
intercepted.  It  must  be  present  for  the  WinSetClassMsglnterest 
call  to  have  an  effect. 

*/ 

BOOL  MsgControlHook(HAB  hab.LONG  idContext,  /*  this  hook  can  */ 
HWND  hwnd,  PSZ  pszClassname,  /*  be  given  any  */ 

ULONG  ulMsgclass,  /*  name.  */ 

LONG  idControl,  PBOOL  fSuccess) 

{ 

/*  ...  */ 

} 
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#define  INCL_WINTHUNKAPI  /*  Or  use  INCL_WIN  or  INCL_PM  7 


BOOL  WinSetClassThunkProc  (PSZ  pszClassName,  PFN  pthunkpr) 


This  function  associates  a pointer-conversion  procedure  with  a window  class. 

Parameters 

pszCiassName  (PSZ)  - input 
Window-class  name. 

pthunkpr  (PFN)  - input 

Pointer-conversion  procedure  identifier: 

NULL  Any  existing  pointer-conversion  procedure  is  dissociated  from  this  class. 

By  default,  a class  has  no  pointer-conversion  procedure  associated  with  it. 

Other  The  pointer-conversion  procedure  to  be  associated  with  this  class. 

Returns 

Success  indicator: 

TRUE  Successful  completion 
FALSE  An  error  occurred. 

Remarks 

This  function  does  not  alter  the  pointer-conversion  procedure  associated  with  any  existing  window. 
It  changes  the  pointer-conversion  procedure  that  will  be  associated  with  a window  created  with  a 
subsequent  WinCreateWindow  or  WinCreateStdWindow  function. 


Related  Functions 

• WinQueryClassThunkProc 

• WinQueryWindowModel 

• WinQueryWindowThunkProc 

• WinSetWindowThunkProc 
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WinSetClassThunkProc  - 

Set  Class  Pointer-Conversion  Procedure 


Example  Code 

This  example  sets  the  pointer  conversion  procedure  of  the  window  class,  given  that  we  have  an 
anchor-block  handle. 

fdefine  INCL_WINWINDOWMGR 
fdefine  INCL.WINTHUNKAPI 
finclude  <0S2.H> 

LONG  thunkpr(LONG  *p);  /*  prototype  definition.  */ 
main() 

{ 

HAB  hab; 

PFN  pfn; 

char  ‘classname; 

WinQueryClassName(hab, 

sizeof(classname) , 
classname) ; 

Wi nSetCl assThunkProc(cl  assname , 

(PFN)thunkpr) ; 


} 

LONG  thunkpr(LONG  *p) 

{ 

/*  16-bit  to  32-bit  pointer  conversion  procedure.  */ 

} 
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Set  Clipboard  Data 

#define  INCL_WINCLIPBOARD  /*  Or  use  INCL_WIN  or  INCL_PM  */ 


BOOL  WinSetClipbrdData  (HAB  hab,  ULONG  ulh,  ULONG  ulfmt,  ULONG  flFmtlnfo) 


This  call  puts  data  into  the  clipboard. 

Parameters 

hab  (HAB)  - input 

Anchor-block  handle. 

ulh  (ULONG)  — input. 

Handle. 

General  handle  to  the  data  object  being  set  into  the  clipboard.  If  NULLHANDLE,  a 
WMRENDERFMT  message  is  sent  to  the  clipboard-owner  window  to  render  the  format  when 
WinQueryClipbrdData  is  called  with  the  specified  format. 

Once  the  data  has  been  set  into  the  clipboard,  this  handle  can  no  longer  be  used  by  the 
application. 

If  CFI_POINTER  is  specified,  this  parameter  contains  a pointer  to  memory.  The  memory  must 
have  been  allocated  as  unnamed  and  shareable,  by  DosAilocSharedMem  with  the 
OBJ_GIVEABLE  attribute. 

ulfmt  (ULONG)  - input 
Format. 

Clipboard  format  of  the  data  object  referenced  by  ulh. 

The  standard  clipboard  formats  are  shown  in  the  following  list.  In  addition  to  these  predefined 
formats,  any  format  value  registered  through  the  standard  system  atom  manager  displays  this 
format  in  preference  to  privately-formatted  data. 

CF_TEXT  Text  format.  Each  line  ends  with  a carriage-return/line-feed  combination. 

Tab  characters  separate  fields  within  a line.  A NULL  character  signals  the 
end  of  the  data. 

Text  display  format  associated  with  private  format. 

Bit  map. 

Bit-map  display  format  associated  with  private  format. 

Metafile. 

CF_DSPMETAFILE  Metafile  display  format  associated  with  private  format. 

CF_PALETTE  Palette. 

flFmtlnfo  (ULONG)  - input 
Information. 

Information  about  the  type  of  data  referenced  by  the  ulh  parameter. 

Memory  Model 

One  and  only  one  of  CFI_POINTER  and  CFI_HANDLE  must  be  specified,  unless 
CFI_OWNERDISPLAY  is  also  specified. 

CFI_POINTER  The  ulh  parameter  is  a flat  pointer  to  the  object. 

When  this  memory  model  is  specified,  the  system: 


CF_DSPTEXT 

CFBITMAP 

CFDSPBITMAP 

CFMETAFILE 
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• saves  the  address  (accessing  it  from  the  shell  process),  so  that  if 
the  setting  application  terminates  normally  or  abnormally,  the  data 
is  still  available. 

• frees  the  memory  from  the  setting  process,  so  that  the  setting 
application  may  no  longer  use  it. 

CFI_POINTER  must  be  specified  if  the  ulfmt  parameter  is  CF_TEXT  or 
CF_DSPTEXT. 

CFI  HANDLE  The  ulh  parameter  is  the  handle  to  a metafile  or  bit  map. 

This  must  be  specified  if  the  ulfmt  parameter  is  CF_BITMAP, 
CF_DSPBITMAP,  CF_METAFILE  or  CF_DSPMETAFILE. 

Usage  Flags 

CFI_OWNERFREE  Handle  is  not  freed  by  WinEmptyClipbrd.  The  application  must  free  the 
data  if  necessary. 

CFI_OWNERDISPLAY  This  flag  indicates  that  the  format  is  drawn  by  the  clipboard  owner  in  the 
clipboard  viewer  window  by  means  of  the  WMPAINTCLIPBOARD 
message.  The  ulh  parameter  should  be  NULL. 

Returns 

Data-placed  indicator. 

Indicates  whether  data  is  placed  into  clipboard  by  this  call: 

TRUE  Data  placed  into  clipboard. 

FALSE  Data  is  not  placed  into  clipboard,  either  an  error  occurred,  or  ulh  is  NULL. 

Possible  returns  from  WinGetLastError 

PMERR  INVALID  FLAG  An  invalid  bit  was  set  for  a parameter.  Use  constants 

defined  by  PM  for  options,  and  do  not  set  any  reserved 
bits. 

PMERRJNVALID_INTEGER_ATOM  The  specified  atom  is  not  a valid  integer  atom. 

Remarks 

Data  of  the  specified  format,  already  in  the  clipboard,  is  freed  by  this  call. 

An  object  passed  to  the  clipboard  becomes  the  property  of  the  system,  and  is  not  deleted  when  the 
process  that  created  it  terminates. 


Related  Functions 

• WinCloseClipbrd 

• WinEmptyClipbrd 

• WinEnumClipbrdFmts 

• WinOpenClipbrd 

• WinQueryClipbrdData 

• WinQueryClipbrdFmtlnfo 

• WinQueryClipbrdOwner 

• WinQueryClipbrdViewer 

• WinSetClipbrdOwner 

• WinSetClipbrdViewer 
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Set  Clipboard  Data 


Related  Messages 

• WM_RENDERFMT 

• WM  PAINTCLIPBOARD 


Example  Code 

This  example  puts  a bit  map  into  the  clipboard. 

fdefine  INCL_WINCLIPBOARD 
finclude  <0S2.H> 

HAB  hab;  /*  anchor-block  handle.  */ 

HBITMAP  bmap;  /*  bit-map  handle.  */ 

WinOpenCl  ipbrd(hab) ; 

WinSetCl ipbrdData(hab, 

(U LONG) bmap, 

CF_BITMAP, 

CFI_HANDLE);  /*  tells  the  system  that  the  */ 
/*  bmap  parameter  is  a handle  */ 
/*  to  a bit  map.  */ 

WinCloseClipbrd(hab) ; 
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Set  Clipboard  Owner 


#define  INCL_WINCLIPBOARD  /*  Or  use  INCL_WIN  or  INCL_PM  */ 


BOOL  WinSetClipbrdOwner  (HAB  hab,  HWND  hwnd) 


This  function  sets  the  current  clipboard-owner  window. 


Parameters 

hab  (HAB)  — input 

Anchor-block  handle. 

hwnd  (HWND)  - input 

Window  handle  of  the  new  clipboard  owner: 

NULLHANDLE  Clipboard-owner  window  is  released  and  no  new  clipboard-owner  window  is 
established. 

Other  Window  handle  of  the  new  clipboard  owner. 

Returns 

Success  indicator: 

TRUE  Successful  completion 
FALSE  Error  occurred. 

Possible  returns  from  WinGetLastError 

PMERR  INVALID  HWND  An  invalid  window  handle  was  specified. 

Remarks 

The  clipboard  owner  window  receives  the  following  clipboard-related  messages  at  appropriate 
times: 

WM_DESTROYCLIPBOARD 

WM_HSCROLLCLI  PBO  ARD 

WM_PAINTCLIPBOARD 

WM_RENDERFMT 

WM_RENDERALLFMTS 

WM_SIZECLIPBOARD 

WM_VSCROLLCLIPBOARD. 

Related  Functions 

• WinCloseClipbrd 

• WinEmptyClipbrd 

• WinEnumClipbrdFmts 

• WinOpenClipbrd 

• WinQueryClipbrdData 

• WinQueryClipbrdFmtlnfo 

• WinQueryClipbrdOwner 

• WinQueryClipbrdViewer 

• WinSetClipbrdData 

• WinSetClipbrdViewer 


8-452  PM  Programming  Reference 


WinSetCiipbrdOwner  - 
Set  Clipboard  Owner 


Related  Messages 

• WM_DESTROYCLIPBOARD 

• WM_HSCROLLCLIPBOARD 

• WM_PAINTCLIPBOARD 

• WM_RENDERALLFMTS 

• WM_RENDERFMT 

• WM_SIZECLIPBOARD 

• WM  VSCROLLCLIPBOARD 


Example  Code 

This  example  places  a bit  map  into  the  clipboard. 

fdefine  INCL_WINCLIPBOARD 
finclude  <0S2.H> 

HAB  hab ; /*  anchor-block  handle.  */ 

HBITMAP  bmap;  /*  bit-map  handle.  */ 

HWND  hwnd; 

WinOpenCl ipbrd(hab) ; 

WinSetCl ipbrdOwner(hab, 

hwnd);  /*  window  handle  of  the  clipboard  */ 
/*  owner.  */ 

Wi  nSetCl i pbrdData (hab, 

(ULONG)bmap, 

CF_BITMAP, 

CFI_HANDLE) ; /*  tells  the  system  that  the  */ 
/*  bmap  parameter  is  a handle  */ 
/*  to  a bit  map.  */ 

WinCloseCl  ipbrd(hab) ; 
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#define  INCL_WINCLIPBOARD  /*  Or  use  INCL_WIN  or  INCL_PM  7 


BOOL  WinSetClipbrdViewer  (HAB  hab,  HWND  HwndNewCiipViewer) 


This  function  sets  the  current  clipboard-viewer  window  to  a specified  window. 

Parameters 

hab  (HAB)  - input 

Anchor-block  handle. 

hwndNewCllpVlewer  (HWND)  - input 

Window  handle  of  the  new  clipboard  viewer: 

NULLHANDLE  The  clipboard-viewer  window  is  released  and  no  new  clipboard-viewer  window 
is  established. 

Other  Window  handle  of  the  new  clipboard  viewer. 

Returns 

Success  indicator: 

TRUE  Valid,  new  clipboard-viewer  window  established 
FALSE  There  is  no  new  clipboard-viewer  window  established. 

Possible  returns  from  WinGetLastError 

PMERRINVALIDHWND  An  invalid  window  handle  was  specified. 

Remarks 

The  clipboard-viewer  window  receives  the  WM  DRAWCLIPBOARD  message  when  the  contents  of  the 
clipboard  change.  This  allows  the  viewer  window  to  display  an  up-to-date  version  of  the  clipboard 
contents. 

The  clipboard  must  be  open  before  this  function  is  invoked. 


Related  Functions 

• WinCloseClipbrd 

• WinEmptyClipbrd 

• WinEnumClipbrdFmts 

• WinOpenClipbrd 

• WinQueryClipbrdData 

• WinQueryClipbrdFmtlnfo 

• WinQueryClipbrdOwner 

• WinQueryClipbrdViewer 

• WinSetClipbrdData 

• WinSetClipbrdOwner 

Related  Messages 

• WM_DRAWCLIPBOARD 
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Set  Clipboard  Viewer 


Example  Code 

This  example  shows  how  a window  views  the  clipboard  contents. 

fdefine  INCL.WINCLIPBOARD 
finclude  <0S2.H> 

ULONG  hclipbrdData; 

HAB  hab;  /*  anchor-block  handle.  */ 

HBITMAP  bmap;  /*  bit-map  handle.  */ 

HWND  hwnd; 


WinOpenCl ipbrd(hab) ; 

WinSetClipbrdViewer (hab, 

hwnd);  /*  window  handle  of  the  clipboard  */ 
/*  viewer.  */ 

hclipbrdData  = WinQueryCl ipbrdData(hab, 

CF_TEXT) ; 


WinCloseCl  ipbrd(hab) ; 
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#define  INCL_WINCOUNTRY  /*  Or  use  INCL_WIN  or  INCL_PM  */ 


BOOL  WinSetCp  (HMQ  hmq,  ULONG  ulCodePage) 


This  function  sets  the  code  page  for  a queue. 

Parameters 

hmq  (HMQ)  - input 

Message-queue  handle. 

ulCodePage  (ULONG)  - input 
Code  page. 

Either  of  the  two  ASCII  code  pages  specified  in  CONFIG.SYS  can  be  selected. 


Returns 

Success  indicator: 

TRUE  Successful  completion 
FALSE  Error  occurred. 

Possible  returns  from  WinGetLastError 

PMERRINVALIDHMQ  An  invalid  message-queue  handle  was  specified. 

PMERR_RESOURCE_NOTJFOUND  The  specified  resource  identity  could  not  be  found. 

Related  Functions 

• WinCpTranslateChar 

• WinCpTranslateString 

• WinQueryCp 

• WinQueryCpList 

Example  Code 

This  example  sets  the  code  page  for  a message  queue  to  850  if  it  is  not  already  set. 

fdefine  INCL_WINCOUNTRY 
finclude  <0S2.H> 

HMQ  hmq; 

if(WinQueryCp(hmq)  !=  850) 

{ 

WinSetCp(hmq,  850); 

} 
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Set  Desktop  Background 


#define  INCL  WINWINDOWMGR  /*  Or  use  INCL_WIN  or  INCL_PM  */ 


H BITMAP  WinSetDesktopBkgnd  (HWND  hwndDeskTop,  PDESKTOP  pDeskTopState) 


This  function  sets  the  desktop  window  state. 


Parameters 

hwndDeskTop  (HWND)  - input 
Desktop-window  handle: 

pDeskTopState  (PDESKTOP)  - input 
Desktop-state  structure. 

If  the  fl  parameter  has  the  SDT_LOADFILE  flag  set  then  the  szFile[MAX_FILENAME]  is  used  to 
load  the  bit  map.  If  the  SDT_NOBKGND  flag  is  set,  then  the  background  is  unaffected  although 
the  bit-map  file  may  still  be  loaded  and  tiled,  or  scaled  as  requested. 


Returns 

Desktop  background  bit-map  handle  loaded  or  set: 

NULLHANDLE  Error  occurred. 

Other  Bit-map  handle  loaded,  set,  or  both  for  desktop  background.  The  bit-map 

handle  returned  may  be  different  from  that  passed  into  call  if  any  scaling  or 
tiling  is  performed. 

Possible  returns  from  WinGetLastError 

PMERR  INVALID  HPTR  An  invalid  pointer  handle  was  specified. 

PMERR_INVALID_HWND  An  invalid  window  handle  was  specified. 

Remarks 

This  function  allows  an  application  to  present  an  image  in  the  background  of  the  desktop  window. 
This  application  must  be  acting  as  the  OS/2  PM  shell  in  place  of  the  IBM  supplied  shell.  If  the  IBM 
supplied  shell  is  executing  it  maintains  control  of  the  background  of  the  desktop  window,  and 
WinSetDesktopBkgnd  will  have  no  effect  on  the  desktop  window  background,  but  will  indicate  a 
successful  return  code.  The  background  of  the  desktop  window  is  that  portion  of  the  desktop  on 
which  no  other  windows  have  been  painted. 

The  system  assumes  ownership  of  the  bit  map  which  forms  the  desktop  background.  This  implies 
that  once  the  bit  map  is  set  to  form  the  desktop  background,  it  is  no  longer  available  to  an  application 
and  therefore  must  not  be  associated  with  any  application  presentation  space  or  any  symbol  set 
LCID.  The  system  repaints  the  desktop  background  automatically  to  show  any  changes. 

The  most  recent  invocation  of  this  function  sets  the  state  of  the  desktop  background.  Consequently, 
any  application  which  sets  the  desktop  background  must  be  aware  that  changi  ng  the  desktop 
background  every  time  the  application  is  activated,  which  implies  the  repainting  of  the  whole 
desktop,  could  be  distracting,  if  not  disorienting,  to  the  user.  Therefore,  such  an  application  should 
determine  if  the  correct  desktop  background  is  already  showing  by  processing  the  WM  ACTIVATE 
message  and  if  its  usactive  parameter  is  set  to  TRUE,  determining  the  desktop  background  state  by 
using  the  WinQueryDesktopBkgnd  function  and  checking  the  bit-map  handle  of  the  current  desktop 
background  with  the  desired  bit-map  handle. 


When  setting  a new  desktop  background,  it  is  important  to  ensure  that  any  previous  desktop 
background  bit  map  is  destroyed,  in  order  to  prevent  the  system  becoming  cluttered  with  unused  bit 
maps. 
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Set  Desktop  Background 

Related  Functions 

• WinQueryDesktopBkgnd 


Example  Code 

This  example  sets  the  desktop  background  with  a bit  map  if  it  is  not  already  set. 

fdefine  INCL_WINDESKTOP 
fdefine  INCL_WINWINDOWMGR 
finclude  <0S2.H> 

HWND  hwndDeskTop; 

HAB  hab; 

DESKTOP  DeskTopState; 

HBITMAP  hbm; 

HBITMAP  hbm_user; 


WinQueryDesktopBkgnd(HWND_DESKTOP, 

SDeskTopState); 

if  (hbm_user  !=  DeskTopState. hbm) 

{ 


DeskTopState.fi  = SDT_LOADFI LE ; 

/*  the  szFile  is  used  to  load  the  bit  map  because*/ 
/*  the  fl  parameter  is  set  to  SDT_LOADFILE.  */ 
strcpy (DeskTopState . szFi 1 e , " frui t . bmp" ) ; 

DeskTopState. hbm  = hbm_user; 

WinSetDesktopBkgnd (hwndDeskTop, 

UDeskTopState) ; 


} 
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WinSetDIgltemShort  - 
Set  Dialog  Item  Short 


#define  INCL_WINDIALOGS  /*  Or  use  INCL_WIN  or  INCL_PM.  Also  in  COMMON  section  */ 


BOOL  WinSetDIgltemShort  (HWND  hwndDIg,  ULONG  Idltem,  USHORT  usValue,  BOOL  fSIgned) 


This  function  converts  an  integer  value  into  the  text  of  a dialog  item. 


Parameters 

hwndDIg  (HWND)  - input 
Parent-window  handle. 

Idltem  (ULONG)  - input 

Identity  of  the  child  window  whose  text  is  to  be  changed. 

usValue  (USHORT)  - input 

Integer  value  used  to  generate  the  dialog  item  text. 

fSIgned  (BOOL)  - input 
Sign  indicator: 

TRUE  Signed  integer  value 
FALSE  Unsigned  integer  value. 

Returns 

Success  indicator: 

TRUE  Successful  completion 
FALSE  Error  occurred. 

Possible  returns  from  WinGetLastError 

PMERRINVALIDHWND  An  invalid  window  handle  was  specified. 

Remarks 

The  text  produced  is  an  ASCII  string. 

This  function  is  valid  for  any  window  with  children;  however,  it  is  typically  used  for  dialog  items  in  a 
dialog  window. 


Related  Functions 

• WinQueryDIgltemShort 

• WinQueryDIgltemText 

• WinQueryDIgltemTextLength 

• WinQueryWindowText 

• WinQueryWindowTextLength 

• WinSetDIgltemText 

• WinSetWindowText 
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WinSetDIgltemShort  - 
Set  Dialog  Item  Short 


Example  Code 

This  example  gets  the  text  from  a Dialog  Box  entry  field  as  an  integer  value. 

fdefine  INCL_WINDIALOGS 
#define  INCL_WINBUTTONS 
finclude  <0S2.H> 
fdefine  IDJNTRYFLO  900 
fdefine  EMJETTEXTLIMIT  2 
HAB  hab; 

HWND  hwnd; 

ULONG  msg; 

switch (msg) 

{ 

case  WMJNITDLG: 

/*  set  entry  field  text  limit.  */ 

Wi nSendDl gItemMsg(hwnd , 

/*  identifier  of  the  entry  field  window,  which  is  */ 

/*  a child  of  the  the  window  defined  by  hwnd.  */ 

(ULONG)  IDJNTRYFLO, 

(ULONG) EMJETTEXTLIMIT,  /*  Limit  length  */ 

/*  MPFR0M2SH0RT  macro  is  of  the  form  (low  2 bytes,  */ 

/*  high  2 bytes),  the  the  number  passed  is  simply  2.  */ 
MPFROM2SHORT(2,0) , 

(MPARAM)0) ; 

/*  set  entry  field  to  12.  */ 

WinSetDlgItemShort(hwnd,  IDJNTRYFLD,  (SHORT)  12, TRUE) ; 

} 
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WinSetDIgltemText  - 
Set  Dialog  Item  Text 


#define  INCL_WINDIALOGS  /*  Or  use  1NCL_WIN  or  INCL_PM.  Also  in  COMMON  section  7 


BOOL  WinSetDIgltemText  (HWND  hwndDIg,  ULONG  Idltem,  PSZ  pszText) 


This  function  sets  a text  string  in  a dialog  item. 


Parameters 

hwndDIg  (HWND)  - input 
Parent-window  handle. 


Idltem  (ULONG)  - input 

Identity  of  the  child  window  whose  text  is  to  be  set. 

pszText  (PSZ)  - input 
Source  string. 

This  is  the  text  string  that  is  to  be  set  into  the  dialog  item. 


Returns 

Success  indicator: 

TRUE  Successful  completion 
FALSE  Error  occurred. 

Possible  returns  from  WinGetLastError 

PMERR  INVALID  HWND  An  invalid  window  handle  was  specified. 

Remarks 

This  function  is  valid  for  any  window  with  children.  However,  it  is  typically  used  for  dialog  items  in  a 
dialog  window. 

This  function  is  equivalent  to: 

WinSetWindowText(WinWindowFromID(hwndDlg,  idltem,  pszText); 

Related  Functions 

• WinQueryDIgltemShort 

• WinQueryDIgltemText 

• WinQueryDIgltemTextLength 

• WinQueryWindowText 

• WinQueryWindowTextLength 

• WinSetDIgltemShort 

• WinSetWindowText 
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WinSetDIgltemText 
Set  Dialog  Item  Text 


Example  Code 

This  example  sets  the  text  "CALENDAR"  in  a dialog  box. 

fdefine  INCL_WINDIALOGS 
finclude  <0S2.H> 
fdefine  ID_DLG_CALENDAR  900 
HWND  hwndDlg; 

Wi nQuerySetOl gltemText (hwndDl g , 

ID_DLG_CALENDAR, 
"CALENDAR") ; 
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WinSetFilelcon  - 
Set  File  Icon 


#define  INCLJVINWORKPLACE 

BOOL  WinSetFilelcon  (PSZ  pszFlleName,  PICONINFO  plcon) 

The  WinSetFilelcon  function  will  set  the  icon  on  the  file  specified  by  pszFileName  to  be  that  specified 
by  picon. 

Parameters 

pszFlleName  (PSZ)  - input 

A pointer  to  a zero-terminated  string  which  contains  the  name  of  the  file  whose  icon  will  be  set. 
plcon  (PICONINFO)  - input 

A pointer  to  an  ICONINFO  structure  containing  an  icon  specification. 

Returns 

Success  indicator: 

TRUE  Successful  completion 
FALSE  Error  occurred. 

Remarks 

The  specified  icon  is  written  to  the  file's  .ICON  extended  attribute. 

Related  Functions 

• WinLoadFilelcon 

• WinFreeFilelcon 
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WinSetFocus 
Set  Focus 


#define  INCL_WININPUT  /*  Or  use  INCL_WIN  or  INCL_PM.  Also  in  COMMON  section  7 


BOOL  WinSetFocus  (HWND  hwndDeskTop,  HWND  hwndNewFocus) 


This  function  sets  the  focus  window. 

Parameters 

hwndDeskTop  (HWND)  - input 
Desktop-window  handle: 

HWND_DESKTOP  The  desktop-window  handle 

Other  Specified  desktop-window  handle. 

hwndNewFocus  (HWND)  - input 

Window  handle  to  receive  the  focus. 

If  hwndNewFocus  identifies  a desktop  window,  no  window  on  the  device  associated  with  the 
hwndDeskTop  receives  the  focus. 


Returns 

Success  indicator: 

TRUE  Successful  completion 
FALSE  Error  occurred. 

Possible  returns  from  WinGetLastError 

PMERRJNVALID  HWND  An  invalid  window  handle  was  specified. 

Remarks 

This  function  is  equivalent  to  the  WinFocusChange  call  in  which  the  fIFocusChange  parameter  is  set 
to  0. 

If  no  window  has  the  input  focus,  WM_CHAR  messages  are  posted  to  the  queue  of  the  active  window 
and  are  not  thrown  away. 

When  this  function  is  called  a WM_MOUSEMOVE  message  is  posted  regardless  of  whether  the 
pointing  device  pointer  has  actually  moved.  This  ensures  that  the  window  below  the  pointing  device, 
at  that  time,  is  able  to  change  features,  such  as  the  shape  of  the  pointing  device  pointer. 

This  function  requires  the  existence  of  a message  queue. 


Related  Functions 

• WinEnablePhysinput 

• WinFocusChange 

• WinGetKeyState 

• WinGetPhysKeyState 

• WinQueryFocus 

• WinSetKeyboardStateTable 
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WinSetFocus  - 
Set  Focus 


Related  Messages 

• WM_CHAR 

• WM_MOUSEMOVE 

Example  Code 

This  example  gives  the  client  the  focus  if  it  does  not  already  have  it. 

fdefine  INCL_WININPUT 
#i nclude  <0S2.H> 
fdefine  SYS_MENU  900 
HWND  hwndFrame; 

if  (WinQueryFocus(HWND_DESKTOP)  !=  /*  returns  handle  of  */ 

/*  window  with  focus.  */ 

WinWindowFronID (hwndFrame, FID_CLIENT) ) 

{ 

WinSetFocus (HWND_DESKTOP, 

Wi nWindowFromID (hwndFrame, FID_CLIENT) ) ; /*  handle  of  client  */ 

/*  window.  */ 


} 


Chapter  8.  Window  Functions  8-465 


WinSetHook 
Set  Hook 


#define  INCL_WINHOOKS  /*  Or  use  INCL_WIN  or  INCL_PM  */ 


BOOL  WinSetHook  (HAB  hab,  HMQ  hmq,  LONG  IHookType,  PFN  pHookProc, 
HMODULE  Module) 


This  function  installs  an  application  procedure  into  a specified  hook  chain. 

Parameters 

hab  (HAB)  - input 

Anchor-block  handle. 

hmq  (HMQ)  - input 
Queue  identity. 

This  parameter  identifies  the  queue  to  which  the  hook  chain  belongs.  If  hmq  is  set  to 
NULLHANDLE,  the  hook  is  installed  in  the  system  hook  chain.  If  hmq  is  set  to  HMQCURRENT, 
the  hook  is  installed  in  the  message  queue  associated  with  the  current  thread  (calling  thread). 

IHookType  (LONG)  - input 


Hook-chain  type. 

HK_CHECKMSGFILTER 

See  CheckMsgFilterHook. 

HKCODEPAGECHANGE 

See  CodePageChangeHook. 

HKDESTROYWINDOW 

See  Destroy WindowHook. 

HKHELP 

See  HelpHook. 

HKJNPUT 

See  InputHook. 

HKJOURNALPLAYBACK 

See  JournalPlaybackHook. 

HKJOURNALRECORD 

See  JournalRecordHook. 

HKLOADER 

See  LoaderHook. 

HKMSGCONTROL 

See  MsgCtIHook. 

HKMSGFILTER 

See  MsgFilterHook. 

HKREGISTERUSERMSG 

See  RegisterUserMsg. 

HK  SENDMSG 

See  SendMsgHook. 

pHookProc  (PFN)  - input 

Address  of  the  application  hook  procedure. 

Module  (HMODULE)  - input 
Resource  identity. 

Handle  of  the  module  that  contains  the  application  hook  procedure,  as  returned  by  the 
DosLoadModule  or  DosGetModHandle  call.  This  parameter  can  be  NULLHANDLE  when  a queue 
hook  is  being  installed  by  an  application  into  its  own  message  queue. 

When  hooking  a system  hook  this  parameter  must  be  a valid  module  handle. 
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WinSetHook  - 
Set  Hook 


Returns 

Success  indicator: 

TRUE  Successful  completion 
FALSE  An  error  occurred. 

Possible  returns  from  WinGetLastError 

PMERRINVALIDHMQ  An  invalid  message-queue  handle  was  specified. 

PMERR_PARAMETER_OUT_OF_RANGE  The  value  of  a parameter  was  not  within  the  defined  valid 

range  for  that  parameter. 


Remarks 

Queue  hooks  are  called  before  system  hooks. 

This  function  installs  the  hook  at  the  head  of  either  the  system  or  queue  chain.  The  most  recently 
installed  hook  is  called  first. 

Use  the  WinQueryWindowULong  function  to  obtain  the  queue  handle  associated  with  a window 
handle. 

Related  Functions 

• WinCallMsgFilter 

• WinReleaseHook 

Example  Code 

This  example  uses  the  WinSetHook  call  to  intercept  user-input  messages  from  the  application  queue. 

fdefine  INCL_WINH00KS 
finclude  <0S2.H> 

void  RecordHook(HAB  hab,  PQMSG  pqmsg);  /*  prototype  of  hook  */ 

/*  procedure.  */ 

samp() 

{ 

HAB  hab; 

WinSetHook(hab, 

HMQCURRENT, 

HK_JOURNALRECORD, 

(PFN)RecordHook, 

(HMODULE)O);  /*  hook  is  into  application  queue.  */ 

WinReleaseHook(hab, 

HMQCURRENT , 

HK_JOURNALRECORD, 

(PFN)RecordHook, 

(HMODULE)O);  /*  hook  is  into  application  queue,  */ 


} 

/*  This  hook  records  user-input  messages, 
void  RecordHook(HAB  hab,  PQMSG  pqmsg) 

{ 


} 


*/ 


*/ 
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WinSetKeyboardStateTable  - 
Set  Keyboard  State  Table 


#define  INCL_WININPUT  /*  Or  use  INCL_WIN  or  INCL_PM  */ 


BOOL  WinSetKeyboardStateTable  (HWND  hwndDeskTop,  PBYTE  abKeyStateTable,  BOOL  fSet) 


This  function  gets  or  sets  the  keyboard  state. 


Parameters 

hwndDeskTop  (HWND)  - input 
Desktop-window  handle: 

HWND_DESKTOP  The  desktop-window  handle 

Other  Specified  desktop-window  handle. 

abKeyStateTable  (PBYTE)  - input/output 
Key  state  table. 

This  is  a 256-byte  table  indexed  by  virtual  key  value. 

For  any  virtual  key,  the  0x80  bit  is  set  if  the  key  is  down,  and  zero  if  it  is  up.  The  0x01  bit  is  set  if 
the  key  is  toggled,  (pressed  an  odd  number  of  times),  otherwise  it  is  zero. 

fSet  (BOOL)  - input 
Set  indicator: 

TRUE  The  keyboard  state  is  set  from  abKeyStateTable 
FALSE  The  keyboard  state  is  copied  to  abKeyStateTable. 

Returns 

Success  indicator: 

TRUE  Successful  completion 
FALSE  Error  occurred. 

Possible  returns  from  WinGetLastError 

PMERR  INVALID  HWND  An  invalid  window  handle  was  specified. 

Remarks 

This  function  does  not  change  the  physical  state  of  the  keyboard,  but  changes  the  value  returned  by 
WinGetKeyState,  not  WinGetPhysKeyState. 

To  set  the  state  of  a single  key,  first  get  the  entire  table,  modify  the  individual  key,  and  then  set  the 
table  from  the  modified  value. 

Related  Functions 

• WinEnablePhysinput 

• WinFocusChange 

• WinGetKeyState 

• WinGetPhysKeyState 

• WinQueryFocus 

• WinSetFocus 
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WinSetKeyboardStateTable  - 
Set  Keyboard  State  Table 


Example  Code 

This  example  changes  the  value  returned  by  the  WinGetKeyState  for  the  NEWLINE  key. 

Idefine  INCL_WININPUT 
finclude  <0S2.H> 

HWND  hwndDeskTop; 

BYTE  KeyState[257] ; /*  This  is  a 256  byte  table  */ 

/*  indexed  by  virtual  key  */ 

/*  value.  */ 

/*  For  any  virtual  key,  the  */ 

/*  0x80  bit  is  set  if  the  key  */ 

/*  is  down,  and  zero  if  it  is  */ 

/*  up.  The  0x01  bit  is  set  */ 

/*  if  the  key  is  toggled,  */ 

/*  (pressed  an  odd  number  */ 

/*  of  times),  otherwise  it  is  */ 

/*  zero.  */ 

Wi nSetKeyboardStateT abl e(HWND_DESKTOP , 

/*  the  address  of  the  second  element  is  passed  so  that  the  */ 

/*  key  number  corresponds  to  the  array  index  */ 

&KeyState[l] , 

FALSE);  /*  get  a copy  of  the  keyboard  */ 

/*  state.  */ 

KeyState [VK_CAPSLOCK]  |=  0x01;  /*  set  the  CAPSLOCK  key  to  */ 

/*  on  state  */ 

Wi nSetKeyboardStateTabl e ( HWND_DESKTOP , 

&KeyState[l] , 

TRUE);  /*  get  a copy  of  the  keyboard  */ 

/*  state.  */ 
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WinSetLboxItemText  - 
Set  Listbox  Item  Text 


#define  INCL_WINWINDOWMGR  /*  Or  use  INCL_WIN  or  INCL_PM  7 


BOOL  WinSetLboxItemText  (HWND  hwndLbox,  SHORT  sLboxIndx,  PSZ  pszText) 


This  macro  sets  the  text  of  the  list  box  indexed  item  to  buffer. 

Parameters 

hwndLbox  (HWND)  - input 
List  box  handle. 

sLboxIndx  (SHORT)  - input 
Index  of  the  list  box  item. 

pszText  (PSZ)  - input 

Pointer  to  a null  terminated  string. 


Returns 

Success  indicator: 

TRUE  Successful  completion 
FALSE  Error  occurred. 

Remarks 

This  macro  expands  to: 

fdefine  WinSetLboxItemText(hwndLbox,  sLboxIndx,  pszText) 
( (BOOL)WinSendMsg(hwndLbox, 

LM_SETITEMTEXT, 
MPFROMSHORT(sLboxIndx) , 
MPFROMP(pszText))) 

This  function  requires  the  existence  of  a message  queue. 

Related  Functions 

• WinSendMsg 

Related  Messages 

• LM  SETITEMTEXT 
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WinSetLboxItemText  - 
Set  Listbox  Item  Text 


Example  Code 

This  example  uses  the  WinSetLboxItemText  call  to  set  the  months  in  a calendar  list  box. 

fdefine  INCL_WINDI ALOGS 
finclude  <0S2.H> 

HWND  hwndLbox; 

SHORT  i; 

typedef  char  MONTH [12]; 

MONTH  months[12]  = {"January",  "February",  "March", 

"April",  "May",  "June",  "July", 

"August",  "September",  "October", 

"November",  "December"  }; 


for  (i=0;i<12;i++) 

{ 

Wi nQuerySetDl gltemT ext ( hwndLbox , 
i, 

monthsfi]) ; 

} /*  endfor  */ 
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WinSetMenultemText 
Set  Menu  Item  Text 


#define  INCL_WINWINDOWMGR  /*  Or  use  INCL_WIN  or  INCL_PM  7 


BOOL  WinSetMenultemText  (HWND  hwndMenu,  USHORT  usld,  PSZ  pszText) 


This  macro  sets  the  text  for  Menu  indexed  item  to  buffer. 

Parameters 

hwndMenu  (HWND)  - input 
Menu  window  handle. 

usld  (USHORT)  - input 

Identity  of  the  menu  item. 

pszText  (PSZ)  - input 
Text  for  the  menu  item. 


Returns 

Success  indicator: 

TRUE  Successful  completion 
FALSE  Error  occurred. 

Remarks 

This  macro  expands  to: 

fdefine  WinSetMenultemText  (hwndMenu,  usld,  pszText) 
( (BOOL)WinSendMsg(hwndMenu, 

MM_SETITEMTEXT, 

MPFROMSHORT(id) , 
MPFROMP(pszText))) 


This  function  requires  the  existence  of  a message  queue. 

Related  Functions 

• WinSendMsg 

Related  Messages 

• MM  SETITEMTEXT 


Example  Code 

This  example  sets  the  options  text  in  a menu. 

fdefine  INCL_WINWINDOWMGR 
finclude  <0S2.H> 
fdefine  IDM_0PTI0NS  900 
HWND  hwndMenu; 

Wi nQuerySetMenuItemText (hwndMenu , 
IDM_0PTI0NS, 
"Options"); 
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WinSetMsglnterest  - 
Set  Message  Interest 


#define  INCL_WINMESSAGEMGR  /*  Or  use  INCL_WIN  or  INCL_PM  */ 

BOOL  WinSetMsglnterest  (HWND  hwnd,  ULONG  ulMsgClass,  LONG  IControl) 

This  function  sets  a window’s  message  interest. 

Parameters 

hwnd  (HWND)  - input 
Window  handle. 

ulMsgClass  (ULONG)  - input 

Message  class  to  have  interest  level  set: 

msgld  A single  message  identity  (for  example,  WM_SHOW) 

SMIMALL  All  messages  (except  for  WM_QUIT  if  IControl  is  SMI_AUTODISPATCH  or 
SMI_NOINTEREST). 

IControl  (LONG)  - input 

Interest-identifier  for  the  message  class: 

SMI_RESET  Revert  to  interest  specified  for  the  window  class. 

SMIJNTEREST  Interested  in  the  messages. 

SMI_NOINTEREST  Not  interested  in  the  messages. 

SMIAUTODISPATCH  Interested  in  the  message  or  messages,  but  they  are  to  be  automatically 
dispatched  to  the  window  procedure. 

Returns 

Interest-changed  indicator: 

TRUE  I nterest  successful  ly  changed 
FALSE  Interest  not  successfully  changed. 

Possible  returns  from  WinGetLastError 

PMERRJNVALID  HWND  An  invalid  window  handle  was  specified. 

Remarks 

This  function  has  no  effect  unless  the  MsgCtIHook  hook,  which  is  invoked  by  this  function,  has  been 
set.  The  interest  for  WM_QUIT  cannot  be  set  to  SMI  AUTODISPATCH  using  SMIM_ALL,  because 
WM_QUIT  is  the  normal  means  of  terminating  an  application.  It  can  be  set  specifically,  if  required. 
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Set  Message  Interest 


Related  Functions 

• WinBroadcastMsg 

• WinCreateMsgQueue 

• WinDestroyMsgQueue 

• WinDispatchMsg 

• WinGetDIgMsg 

• WinGetMsg 

• WinlnSendMsg 

• WinPeekMsg 

• WinPostMsg 

• WinPostQueueMsg 

• WinQueryMsgPos 

• WinQueryMsgTime 

• WinQueryQueuelnfo 

• WinQueryQueueStatus 

• WinRegisterllserDatatype 

• WinRegisterllserMsg 

• WinSendDIgltemMsg 

• WinSendMsg 

• WinSetClassMsglnterest 

• WinSetMsgMode 

• WinSetSynchroMode 

• WinWaitMsg 

Example  Code 

This  example  uses  the  WinSetMsglnterest  call  to  set  the  message  interest  of  a window  to  only 
WM_SHOW  messages. 

fdefine  INCL_WINMESSAGEMGR 
fdefine  INCL_WINH00KS 
finclude  <0S2.H> 

HWND  hwnd; 

HAB  hab;  ;f-- 

BOOL  f Success; 

/*  Hook  Procedure  Prototype  */ 


BOOL  MsgCt1Hook(HAB  hab, LONG  fdContext,  /*  this  hook  can  */ 

HWND  hwnd,  PSZ  pszClassname,  /*  be  given  any  */ 

ULONG  ul Msgclass,  /*  name.  */ 

LONG  idControl,  PBOOL  f Success) ; 

main() 

{ 


/*  This  function  passes  the  hook 


procedure  address  to  the  system. 


*/ 


WinSetHook(hab, 

(HMQ)O , 

MCHK_CLASSMSGINTEREST, 
(PFN)MsgCtlHook, 
(HMODULE)O) ; /*  hook  is 


into  application  queue. 


*/ 


/* 

This  function  sets  the  message  interest  of  a window  class. 

*/ 

WinSetMsglnterest (hab, 

WM_SH0W, 

SM I_AUT0DI SPATCH ) ; /*  interested  in  the  */ 
/*  messages,  but  they  are  to  */ 
/*  be  automatically  dispatched  */ 
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Set  Message  Interest 

/*  to  the  window  procedure.  */ 


} 

BOOL  MsgCt1Hook(HAB  hab.LONG  idContext,  /*  this  hook  can  */ 

HWND  hwnd,  PSZ  pszClassname,  /*  be  given  any  */ 

ULONG  ulMsgclass,  /*  name.  */ 

LONG  idControl,  PBOOL  fSuccess) 

{ 

/*  ...  */ 

} 
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WinSetMsgMode  - 
Set  Message  Mode 


#define  INCL_WINMESSAGEMGR  /*  Or  use  INCL_WIN  or  INCL_PM.  Also  in  COMMON  section  */ 


BOOL  WinSetMsgMode  (HAB  hab,  PSZ  pszClassName,  LONG  IControl) 


This  function  indicates  the  mode  for  the  generation  and  processing  of  messages  for  the  private 
window  class  of  an  application. 

Parameters 

hab  (HAB)  - input 

Anchor  block  handle. 

pszClassName  (PSZ)  - input 
Window  class  name. 

IControl  (LONG)  - input 

Message  mode  identifier. 

SMD_DELAYED  The  generation  of  messages  may  be  delayed 
SMDJMMEDIATE  The  generation  of  messages  will  not  be  delayed. 

Returns 

Message  delay  indicator: 

TRUE  Message  mode  successfully  set 
FALSE  Message  mode  not  successfully  set. 

Possible  returns  from  WinGetLastError 

PMERR  INVALID  HWND  An  invalid  window  handle  was  specified. 

Remarks 

This  function  has  no  effect  unless  the  MsgCtIHook  hook,  which  is  invoked  by  this  function,  has  been 
set. 
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Set  Message  Mode 


Related  Functions 

• WinBroadcastMsg 

• WinCreateMsgQueue 

• WinDestroyMsgQueue 

• WinDispatchMsg 

• WinGetDIgMsg 

• WinGetMsg 

• WinlnSendMsg 

• WinPeekMsg 

• WinPostMsg 

• WinPostQueueMsg 

• WinQueryMsgPos 

• WinQueryMsgTime 

• WinQueryQueuelnfo 

• WinQueryQueueStatus 

• WinRegisterUserDatatype 

• WinRegisterllserMsg 

• WinSendDIgltemMsg 

• WinSendMsg 

• WinSetClassMsglnterest 

• WinSetMsglnterest 

• WinSetSynchroMode 

• WinWaitMsg 


Example  Code 

This  example  uses  the  WinSetMsgMode  call  to  set  the  a delayed  message  processing  mode  for 
private  window  class  "Generic". 

Idefine  INCL_WINWINDOWMGR 
Idefine  INCL_WINMESSAGEMGR 
linclude  <0S2.H> 

HWND  hwnd; 

HAB  hab; 

PFNWP  GenericWndProc; 

CHAR  szC1assName[]  = "Generic";  /*  window  class  name  */ 


if  (!WinRegisterClass(hab, 
szCl assName, 
GenericWndProc, 

OL, 

0)); 

return  (FALSE); 


/*  anchor-block  handle  */ 
/*  class  name  */ 
/*  window  procedure  */ 
/*  window  style  */ 


/*  amount  of  reserved  memory  */ 


WinSetMsgMode(hab, 

"Generic", 


SMDJDELAYED) ; 
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WinSetMultWindowPos  - 
Set  Multiple  Window  Positions 


#define  INCL_WINWINDOWMGR  /*  Or  use  INCL_WIN  or  INCL_PM  */ 


BOOL  WinSetMultWindowPos  (HAB  hab,  PSWP  aSwp,  ULONG  cCount) 


This  function  performs  the  WinSetWindowPos  function  for  cCount  windows,  using  aSwp,  an  array  of 
structures  whose  elements  correspond  to  the  input  parameters  of  WinSetWindowPos. 


Parameters 

hab  (HAB)  - input 

Anchor-block  handle. 

aSwp(PSWP)  - input 
Array. 

An  array  of  set  window  position  (SWP)  structures.  The  elements  of  each  correspond  to  the  input 
parameters  of  WinSetWindowPos. 

cCount  (ULONG)  - input 
Window  count. 


Returns 

Positioning  success  indicator: 

TRUE  Positioning  succeeded 
FALSE  Positioning  failed. 

Possible  returns  from  WinGetLastError 

PMERRINVALIDHWND  An  invalid  window  handle  was  specified. 

PMERR_INVALID_FLAG  An  invalid  bit  was  set  for  a parameter.  Use  constants 

defined  by  PM  for  options,  and  do  not  set  any  reserved 
bits. 


Remarks 

All  windows  being  positioned  must  have  the  same  parent. 

It  is  more  efficient  to  use  this  function  than  to  issue  multiple  WinSetWindowPos  functions,  as  it 
causes  less  screen  updating.  If  hwnd  specifies  a frame  window,  this  function  recalculates  the  sizes 
and  positions  of  the  frame  controls.  If  the  new  window  rectangle  for  any  frame  control  is  to  be 
empty,  instead  of  resizing  or  repositioning  that  control,  it  is  hidden  by  (SWP_HIDE)  instead.  This 
eliminates  needless  processing  of  windows  that  are  not  visible.  The  window  rectangle  of  the  control 
in  question  is  left  in  its  original  state.  For  example,  if  WinSetWindowPos  is  issued  to  change  the  size 
of  a standard  frame  window  to  an  empty  rectangle,  and  WinQueryWindowRect  is  issued  against  the 
client  window,  the  rectangle  returned  is  not  an  empty  rectangle,  but  the  original  client  rectangle 
before  WinSetWindowPos  was  issued. 

Related  Functions 

• WinGetMinPosition 

• WinQueryActiveWindow 

• WinQueryWindowPos 

• WinSaveWindowPos 

• WinSetActiveWindow 

• WinSetWindowPos 
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WinSetMultWindowPos  - 
Set  Multiple  Window  Positions 


Related  Messages 

• WM_ACTIVATE 

• WM_ADJUSTWINDOWPOS 

• WM_CALCVALIDRECTS 

• WM_MOVE 

• WM_SHOW 

• WM  SIZE 


Example  Code 

This  example  uses  the  WinSetMultWindowPos  to  cascade  up  to  16  main  windows. 

fdefine  INCL_WINWINDOWMGR 
finclude  <0S2.H> 

HWND  ahwnd[16];  /*  array  of  window  handles.  */ 

SWP  aSwp[16];  /*  array  of  SWP  structures.  */ 

HAB  hab; 

SWP  swp; 

LONG  xcoord .ycoord; 

LONG  i=l; 

/*  get  recommended  window  position  */ 

Wi nQueryTaskSi zePos (hab, 

0, 

&swp) ; 

xcoord  = swp.x;  ycoord  = swp.y; 


/*  initialize  array  of  SWP  structures  where  each  is  displaced  */ 
/*  by  (10,10).  */ 

for  ( i =0 ; i <16  ;i++  ) { 
aSwp[i]=swp; 
aSwp[i]  .x=xcoord; 
aSwp[i] .y=ycoord; 
xcoord  +=  10; 
ycoord  +=  10; 

} /*  endfor  */ 


/*  get  a list  of  all  the  main  windows  into  the  ahwnd  array.  */ 
i=0 

henum=Wi nBegi nEnumWi  ndows 
(HWNO_OESKTOP) ; 
do 
{ 

ahwnd  [i]  = WinGetNextWindow 
(henum) ; 

} 

while((ahwnd[i++] !=NULL)  &&  i < 16); 

WinEndEnumWi ndows (henum) ; 

Wi nSetMul tWi ndowPos ( hab , aSwp , i - 1) ; 
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WinSetObjectData  - 
Set  Object  Data 


#define  INCL_WINWORKPLACE 


BOOL  WinSetObjectData  (HOBJECT  object,  PSZ  pszSetupStrlng) 


The  WinSetObjectData  function  is  called  to  set  data  on  a workplace  object. 

Parameters 

object  (HOBJECT)  - input 

Handle  to  a workplace  object. 

pszSetupStrlng  (PSZ)  - input 

A pointer  to  a zero-terminated  string  which  contains  the  object-specific  parameters  to  the  new 
object. 

The  pszSetupString  string  is  extracted  when  the  wpSetup  method  is  called. 

Returns 

Success  indicator. 

TRUE  Successful  completion. 

FALSE  Error  occurred. 

Remarks 

The  WinSetObjectData  function  will  change  settings  on  an  object  that  was  created  with  the 
WinCreateObject  function. 

Related  Functions 

• WinCreateObject 

• WinDestroyObject 
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WinSetOwner  - 
Set  Owner 


#define  INCL_WINWINDOWMGR  /*  Or  use  INCLJ/VIN  or  INCL_PM  */ 


BOOL  WinSetOwner  (HWND  hwnd,  HWND  hwndNewOwner) 


This  function  changes  the  owner  window  of  a specified  window. 


Parameters 

hwnd  (HWND)  - input 

Window  handle  whose  owner  window  is  to  be  changed. 

hwndNewOwner  (HWND)  - input 
Handle  of  the  new  owner: 

NULLHANDLE  The  window  becomes  “disowned” 

Other  Handle  of  the  new  owner  window. 

Returns 

Success  indicator: 

TRUE  Successful  completion 
FALSE  Error  occurred. 

Possible  returns  from  WinGetLastError 

PMERRINVALIDHWND  An  invalid  window  handle  was  specified. 

Remarks 

The  old  owner  window  is  not  locked  by  this  function. 

The  WinQueryWindow  function  can  be  used  to  getthe  handle  of  the  owner  window. 


Related  Functions 

• WinBeginEnumWindows 

• WinEndEnumWindows 

• WinEnumDIgltem 

• WinGetNextWindow 

• WinlsChild 

• WinMultWindowFromIDs 

• WinQueryWindow 

• WinSetParent 

Example  Code 

This  example  uses  the  WinSetOwner  call  to  "disown"  a window. 

fdefine  INCL_WINWINDOWMGR 
finclude  <0S2.H> 

HWND  hwnd;  /*  window  handles.  */ 

WinSetOwner(hwnd, (HWND)0) ; 
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WinSetParent 
Set  Parent 


#define  INCL_WINWINDOWMGR  /*  Or  use  INCL_WIN  or  INCL_PM  */ 


BOOL  WinSetParent  (HWND  hwnd,  HWND  hwndNewParent,  BOOL  (Redraw) 


This  function  sets  the  parent  for  hwnd  to  hwndNewParent. 


Parameters 

hwnd  (HWND)  - input 
Window  handle. 

hwndNewParent  (HWND)  - input 
New  parent  window  handle. 

This  cannot  be  a descendant  of  hwnd. 

If  this  parameter  is  a desktop  window  handle  or  HWND_DESKTOP,  hwnd  becomes  a main 
window. 

If  this  parameter  is  not  equal  to  HWND_OBJECT,  it  must  be  a descendant  of  the  same  desktop 
window  as  hwnd. 

If  this  parameter  is  HWND_OBJECT  or  a window  handle  returned  by  the  WinQueryObjectWindow 
function,  hwnd  becomes  an  object  window. 

(Redraw  (BOOL)  - input 
Redraw  indicator: 

TRUE  If  hwnd  is  visible,  any  necessary  redrawing  of  both  the  old  parent  and  the  new  parent 
windows  is  performed. 

FALSE  No  redrawing  of  the  old  and  new  parent  windows  is  performed.  This  avoids  an  extra 
device  update  when  subsequent  calls  cause  the  windows  to  be  redrawn. 

Returns 

Parent-changed  indicator: 

TRUE  Parent  successfully  changed 
FALSE  Parent  not  successfully  changed. 

Possible  returns  from  WinGetLastError 

PMERRINVALIDHWND  An  invalid  window  handle  was  specified. 

PIMERR_INVALID_FLAG  An  invalid  bit  was  set  for  a parameter.  Use  constants 

defined  by  PM  for  options,  and  do  not  set  any  reserved 
bits. 

Related  Functions 

• WinBeginEnumWindows 

• WinEndEnumWindows 

• WinEnumDIgltem 

• WinGetNextWindow 

• WinlsChild 

• WinMultWindowFromIDs 

• WinQueryWindow 

• WinSetOwner 
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WinSetParent  - 
Set  Parent 


Related  Messages 

• WM_ERASEWINDOW 

• WM_PAINT 


Example  Code 

This  example  uses  the  WinSetParent  call  to  change  a window  to  a main  window. 

Idefine  INCL_WINWINDOWMGR 
linclude  <0S2.H> 

HWND  hwnd;  /*  window  handles.  */ 

WinSetParent(hwnd, 

HWND_DESKTOP, 

TRUE);  /*  do  any  necessary  redrawing  */ 
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WinSetPointer 
Set  Pointer 


#define  INCL_WINPOINTERS  /*  Or  use  INCL_WIN  or  INCL_PM  7 


BOOL  WinSetPointer  (HWND  hwndOeskTop,  HPOINTER  hptrNewPoInter) 


This  call  sets  the  desktop-pointer  handle. 


Parameters 

hwndDeskTop  (HWND)  - input 
Desktop-window  handle: 

HWND_DESKTOP  The  desktop-wi  ndow  handl  e 

Other  Specified  desktop-window  handle. 

hptrNewPoInter  (HPOINTER)  - input 
New  pointer  handle: 

NULL  Remove  pointer  from  the  screen. 

Other  Pointer  handle  associated  with  hwndDeskTop.  Handles  for  application-defined  pointers 
are  returned  by  the  WinLoadPointer  and  WinCreatePointer  calls. 

Returns 

Pointer-updated  indicator: 

TRUE  Pointer  successfully  updated 
FALSE  Pointer  not  successfully  updated. 

Possible  returns  from  WinGetLastError 

PMERRJNVALIDHWND 
PMERRINVALIDHPTR 
PMERRINVCURSORBITMAP 

Remarks 

This  call  is  very  efficient  if  hptrNewPointer  is  the  same  as  the  current  pointer  handle. 


An  invalid  window  handle  was  specified. 

An  invalid  pointer  handle  was  specified. 

An  invalid  pointer  was  referenced  with  WinSetPointer 


Related  Functions 

• WinCreatePointer 

• WinCreatePointerlndirect 

• WinDestroyPointer 

• WinDrawPointer 

• WinLoadPointer 

• WinQueryPointer 

• WinQueryPointerlnfo 

• WinQueryPointerPos 

• WinQuerySysPointer 

• WinSetPointerPos 

• WinShowPointer 
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WinSetPointer  - 
Set  Pointer 


Example  Code 

This  example  calls  WinLoadPointer  to  load  an  application-defined  pointer.  When  processing  the 
WM_MOUSEMOVE  message,  the  loaded  pointer  is  displayed  by  calling  WinSetPointer. 

fdefine  INCL_WININPUT 
fdefine  I NCL_WIN POINTERS 
finclude  <0S2.H> 
fdefine  IDP_CROSSHAIR  900 
HPOINTER  hptrCrossHair; 

USHORT  tnsg; 
switch (msg) 

{ 


case  WM_CREATE : 

hptrCrossHair  = WinLoadPointer(HWND_DESKTOP, 
(ULONG)0,  /*  load  from  .exe  file  */ 

IDP_CROSSHAIR) ; /*  identifies  the  pointer  */ 

case  WM_MOUSEMOVE : 

WinSetPointer(HWND_DESKTOP,  hptrCrossHair) ; 


} 
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WinSetPointerPos  - 
Set  Pointer  Position 


#define  INCL_WINPOINTERS  /*  Or  use  INCL_WIN  or  INCL_PM  */ 


BOOL  WinSetPointerPos  (HWND  hwndDeskTop,  LONG  lx,  LONG  ly) 


This  function  sets  the  pointer  position. 


Parameters 

hwndDeskTop  (HWND)  - input 
Desktop-window  handle: 

HWNDJDESKTOP  The  desktop-window  handle 
Other  Specified  desktop-window  handle. 

ix(LONG)  - input 

x-position  of  pointer  in  screen  coordinates, 
ly  (LONG)  - input 

y-position  of  pointer  in  screen  coordinates. 


Returns 

Pointer  position  updated  indicator: 

TRUE  Pointer  position  successfully  updated 
FALSE  Pointer  position  not  successfully  updated. 

Possible  returns  from  WinGetLastError 

PMERRINVALIDHWND  An  invalid  window  handle  was  specified. 

Related  Functions 

• WinCreatePointer 

• WinCreatePointerlndirect 

• WinDestroyPointer 

• WinDrawPointer 

• WinLoadPointer 

• WinQueryPointer 

• WinQueryPointerlnfo 

• WinQueryPointerPos 

• WinQuerySysPointer 

• WinSetPointer 

• WinShowPointer 

Example  Code 

This  example  calls  WinSetPointer  to  set  the  pointer  at  50,  50  in  Screen  coordinates. 

Idefine  INCL_WINPOINTERS 
finclude  <0S2.H> 


WinSetPointerPos(HWND_DESKTOP, 
(L0NG)50, 
(LONG) 50); 
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WinSetPresParam  - 
Set  Presentation  Parameter 


#define  INCL_WINSYS  /*  Or  use  INCL_WIN  or  INCL_PM  */ 


BOOL  WinSetPresParam  (HWND  hwnd,  ULONG  IdAttrType,  ULONG  cbAttrValueLen, 
PVOID  pAttrValue) 


This  function  sets  a presentation  parameter  for  a window. 

Parameters 

hwnd  (HWND)  - input 
Window  handle. 

IdAttrType  (ULONG)  - input 
Attribute  type  identity. 

This  is  either  one  of  the  system-defined  presentation  parameter  attribute  types  (see  the  id 
parameter  of  the  PAR  AM  data  type),  or  an  application-defined  type. 

cbAttrValueLen  (ULONG)  - input 

Byte  count  of  the  data  passed  in  the  pAttrValue  parameter. 

pAttrValue  (PVOID)  - input 
Attribute  value. 

See  the  abab[7]  parameter  of  the  PARAM  data  type  for  the  values  of  system-defined  attributes. 


Returns 

Success  indicator: 

TRUE  Successful  completion 
FALSE  Error  occurred. 

Possible  returns  from  WinGetLastError 

PMERR  INVALID  HWND  An  invalid  window  handle  was  specified. 

Remarks 

This  function  associates  the  presentation  parameter  attribute  identified  by  idAttrType  with  the 
window  hwnd.  If  the  attribute  already  exists  for  the  window,  its  value  is  changed  to  the  new  value 
specified  by  pAttrValue.  If  the  attribute  does  not  exist,  it  is  added  to  the  window's  presentation 
parameters,  with  the  specified  value.  (See  also  WinQueryPresParam  and  WinRemovePresParam). 

When  a presentation  parameter  is  set,  a WM_PRESPARAMCHANGED  message  is  sent  to  all  windows 
owned  by  the  window  calling  the  WinSetPresParam  function. 


Related  Functions 

• WinDrawBitmap 

• WinDrawBorder 

• WinDrawPointer 

• WinDrawText 

• WinFillRect 

• WinGetSysBitmap 

• WinlnvertRect 

• WinQueryPresParam 

• WinRemovePresParam 

• WinScrollWindow 
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WinSetPresParam  - 
Set  Presentation  Parameter 


Example  Code 

This  example  changes  the  border  color  to  blue, 
fdefine  INCLJIINSYS 

fdefine  INCL_GPIBITMAPS  /*  for  RGB  structure  definition.  */ 
finclude  <0S2.H> 

HWND  hwnd; 

RGB  rgb;  /*  red,  green,  and  blue  color  index.  */ 
rgb.bBlue  = 200; 
rgb.bGreen  = 10; 
rgb.bRed  = 5; 


Wi nSetPresParam ( hwnd , 

PP  B0RDERC0L0R, 
(ULONG)sizeof(RGB) , 
(PVOID) &rgb) ; 
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WinSetRect  - 
Set  Rectangle 


#define  INCL_WINRECTANGLES  I*  Or  use  INCL_WIN  or  INCL_PM  */ 


BOOL  WinSetRect  (HAB  hab,  PRECTL  prclrect,  LONG  ILeft,  LONG  IBottom,  LONG  IRIght, 
LONG  Hop) 


This  function  sets  rectangle  coordinates. 


Parameters 

hab  (HAB)  - input 

Anchor-block  handle. 

prclrect  (PRECTL)  - input/output 
Rectangle  to  be  updated. 

Note:  The  value  of  each  field  in  this  structure  must  be  in  the  range  —32  768  through  32  767.  The 
data  type  WRECT  may  also  be  used,  if  supported  by  the  language. 

ILeft  (LONG)  - input 

Left  edge  of  rectangle. 

IBottom  (LONG)  - input 

Bottom  edge  of  rectangle. 

IRIght  (LONG)  - input 

Right  edge  of  rectangle. 

ITop  (LONG)  - input 

Top  edge  of  rectangle. 


Returns 

Success  indicator: 

TRUE  Successful  completion 
FALSE  Error  occurred. 

Remarks 

This  function  is  equivalent  to  assigning  the  left,  top,  right,  and  bottom  arguments  to  the  appropriate 
fields  of  RECTL. 

Related  Functions 

• WinCopyRect 

• WinEqualRect 

• WinFillRect 

• WinlnflateRect 

• WinlntersectRect 

• WinlsRectEmpty 

• WinOffsetRect 

• WinPtlnRect 

• WinSetRectEmpty 

• WinSubtractRect 

• WinUnionRect 
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WinSetRect  - 
Set  Rectangle 

Example  Code 

This  example  calls  WinQueryWindowRect  to  get  the  dimensions  of  the  window,  and  then  calls 
WinSetRect  to  downsize  it. 

fdefine  INCL_WINRECTANGLES 
finclude  <0S2.H> 

HAB  hab; 

RECTL  rcl ; 

HWND  hwnd; 

WinQueryWindowRect(hwnd,  &rcl);  /*  get  window  dimensions  */ 

WinSetRect(hab,&rcl , 

rcl.xLeft  - 10, 
rcl .yBottom  -10, 
rcl.xRight  - 10, 
rcl.yTop  - 10); 
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WinSetRectEmpty  - 
Set  Rectangle  Empty 


#define  INCL_WINRECTANGLES  /*  Or  use  INCL.WIN  or  INCL_PM  */ 


BOOL  WinSetRectEmpty  (HAB  hab,  PRECTL  prclrect) 


This  function  sets  a rectangle  empty. 


Parameters 

hab  (HAB)  - input 

Anchor-block  handle. 

prclrect  (PRECTL)  - input/output 
Rectangle  to  be  set  empty. 

Note:  The  value  of  each  field  in  this  structure  must  be  in  the  range  —32  768  through  32  767.  The 
data  type  WRECT  may  also  be  used,  if  supported  by  the  language. 


Returns 

Success  indicator: 

TRUE  Successful  completion 
FALSE  Error  occurred. 

Remarks 

This  function  is  equivalent  to  a WinSetRect  (hab,  prclrect,  0,  0,  0,  0)  call. 

Related  Functions 

• WinCopyRect 

• WinEqualRect 

• WinFillRect 

• WinlnflateRect 

• WinlntersectRect 

• WinlsRectEmpty 

• WinOffsetRect 

• WinPtlnRect 

• WinSetRect 

• WinSubtractRect 

• WinUnionRect 

Example  Code 

This  example  calls  WinSetRectEmpty  to  empty  the  rectangle  structure. 

fdefine  INCL_WINRECTANGLES 
#include  <0S2.H> 

HAB  hab; 

RECTL  rcl ; 

WinSetRectEmpty(hab,&rcl ) ; 
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WinSetSynchroMode  - 
Set  Synchronization  Mode 


#define  INCL_WINMESSAGEMGR  /*  Or  use  INCL_WIN  or  INCL_PM.  Also  in  COMMON  section  */ 


BOOL  WinSetSynchroMode  (HAB  hab,  LONG  IMode) 


This  function  is  intended  for  use  in  a distributed  application. 


Parameters 

hab  (HAB)  - input 

Anchor-block  handle. 

IMode  (LONG)  - input 
Synchronization  mode: 

SSM_SYNCHRONOUS  Synchronous  mode 

SSM_ASYNCHRONOUS  Asynchronous  mode 

SSMJMIXED  Mixed  mode. 

Returns 

Success  indicator: 

TRUE  Successful  completion 
FALSE  Error  occurred. 

Remarks 

This  function  allows  an  application  whose  message  queue  is  distributed,  to  synchronize  the 
processing  of  those  messages.  This  is  achieved  by  the  use  of  the  MsgCtIHook  hook  which  is  invoked 
by  this  function. 

Related  Functions 

• WinBroadcastMsg 

• WinCreateMsgQueue 

• WinDestroyMsgQueue 

• WinDispatchMsg 

• WinGetDIgMsg 

• WinGetMsg 

• WinlnSendMsg 

• WinPeekMsg 

• WinPostMsg 

• WinPostQueueMsg 

• WinQueryMsgPos 

• WinQueryMsgTime 

• WinQueryQueuelnfo 

• WinQueryQueueStatus 

• WinRegisterUserDatatype 

• WinRegisterUserMsg 

• WinSendDIgltemMsg 

• WinSendMsg 

• WinSetClassMsglnterest 

• WinSetMsglnterest 

• WinSetMsgMode 

• WinWaitMsg 
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WinSetSynchroMode  - 
Set  Synchronization  Mode 


Example  Code 

This  function  is  intended  for  use  in  an  application  with  a distributed  queue. 

fdefine  INCL_WINMESSAGEMGR 
linclude  <0S2.H> 

HAB  hab; 

Wi nSetSynchroMode ( hab , 

SSM_SYNCHRONOUS) ; /*  synchronous  mode.  */ 
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WinSetSysColors 
Set  System  Colors 


#define  INCL_WINSYS  /*  Or  use  INCL_WIN  or  INCL_PM  */ 


BOOL  WinSetSysColors  (HWND  hwndDeskTop,  ULONG  flOptlons,  ULONG  ulFormat, 
LONG  IStart,  ULONG  ulTablen,  PLONG  aiTable) 


This  function  sets  system  color  values. 

Parameters 

hwndDeskTop  (HWND)  - input 
Desktop-window  handle: 

HWND_DESKTOP  The  desktop-window  handle 

Other  Specified  desktop-window  handle. 

flOptlons  (ULONG)  - input 
Options: 

LCOL_RESET 

The  system  colors  are  all  to  be  reset  to  default  before  processing  the  remainder  of  the  data 
in  this  function. 

LCOL_PURECOLOR 

Color-dithering  should  not  be  used  to  create  colors  not  available  in  the  physical  palette.  If 
this  option  is  set,  only  pure  colors  are  used  and  no  dithering  is  done. 

ulFormat  (ULONG)  - input 

Format  of  entries  in  the  table,  as  follows: 

LCOLFJNDRGB 

Array  of  (index, RGB)  values.  Each  pair  of  entries  is  8-bytes  long,  comprising  4 bytes  for  the 
index,  and  4 bytes  for  the  color  value.  For  system  color  indexes,  see  IStart. 

LCOLF_CONSECRGB 

Array  of  (RGB)  values,  corresponding  to  color  indexes  IStart  upwards.  Each  entry  is  4-bytes 
long. 

IStart  (LONG)  - input 

Starting  system  color  index. 

This  parameter  is  applicable  only  if  the  ulFormat  parameter  is  set  to  LCOLF_CONSECRGB. 

The  number  of  system  colors  (as  defined  below)  is  given  by  SYSCLR_CSYSCOLORS. 

The  following  system  color  indexes  are  defined  (each  successive  index  is  one  larger  than  its 
predecessor): 

SYSCLR_ENTRYFIELD 

Entry  field  and  list  box  background  color. 

SYSCLRMENUDISABLEDTEXT 

Entry  field  background  color. 

SYSCLRMENUHILITE 

Selected  menu  item  text. 

SYSCLR_MENUHILITEBGND 

Selected  menu  item  background. 

SYSCLR_PAGEBACKGROUND 

Notebook  page  background. 
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WinSetSysColors  - 
Set  System  Colors 

SYSCLR_FIELDBACKGROUND 

Inactive  scroll  bar  and  default  control  background  color. 

SYSCLRBUTTONLIGHT 

Light  pushbutton  (3D  effect). 

SYSCLRBUTTONMIDDLE 

Middle  pushbutton  (3D  effect). 

SYSCLR_BUTTONDARK 

Dark  pushbutton  (3D  effect). 

SYSCLRBUTTONDEFAULT 

Pushbutton. 

SYSCLRJTITLEBOTTOM 

Line  drawn  under  title  bar. 

SYSCLRSHADOW 

Drop  shadow  for  menus  and  dialogs. 

SYSCLRJCONTEXT 

Text  written  under  icons  on  the  desktop. 

SYSCLRDIALOGBACKGROUND 

Pop  up  dialog  box  background. 

SYSCLRHILITEFOREGROUND 

Selection  foreground. 

SYSCLRHILITEBACKGROUND 

Selection  background. 

SYSCLRJNACTIVETITLETEXTBKGD 

Background  of  inactive  title  text. 

SYSCLRACTIVETITLETEXTBKGD 

Background  of  active  title  text. 

SYSCLRJNACTIVETITLETEXT 

Inactive  title  text. 

SYSCLRACTIVETITLETEXT 

Active  title  text. 

SYSCLROUTPUTTEXT 

Output  text. 

SYSCLR_WINDOWST  ATICTEXT 

Static  (nonselectable)  text. 

SYSCLRSCROLLBAR 

Active  scroll  bar  background  area. 

SYSCLRBACKGROUND 

Desktop  background. 

SYSCLRACTIVETITLE 

Active  window  title. 

SYSCLRJNACTIVETITLE 

Inactive  window  title. 

SYSCLRMENU 

Menu  background. 

SYSCLR_WINDOW 

Window  background. 
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SYSCLRWINDOWFRAME 

Window  frame  (border  line). 

SYSCLRMENUTEXT 

Normal  menu  item  text. 

S Y SCLRW I N DO  WTEXT 

Window  text. 

SYSCLRTITLETEXT 

Text  in  title  bar,  size  box,  scroll  bar  arrow  box. 

SYSCLRACTIVEBORDER 

Border  fill  of  active  window. 

SYSCLRINACTIVEBORDER 

Border  fill  of  inactive  window. 

SYSCLRAPPWORKSPACE 

Background  of  specific  main  windows. 

SYSCLR_HELPBACKGROUND 

Background  of  help  panels. 

SYSCLRHELPTEXT 

Help  text. 

SYSCLRHELPHILITE 

Highlighted  help  text. 

SYSCLRSHADOWHILITEBGND 

Shadows  of  workplace  object  background  highlight  color. 

SYSCLR_SHADOWHILITEFGND 

Shadows  of  workplace  object  foreground  highlight  color. 

SYSCLRSHADOWTEXT 

Shadows  of  workplace  object  text  color. 

ulTabien  (ULONG)  - input 
Number  of  elements. 

Number  of  elements  supplied  in  alTable.  This  may  be  0 if,  for  example,  the  color  table  is  merely 
to  be  reset  to  the  default.  For  LCOLFJNDRGB  it  must  be  an  even  number. 

alTable  (PLONG)  - input 
Table. 

Start  address  of  the  application  data  area,  containing  the  color-table  definition  data.  The  format 
depends  on  the  value  of  ulFormat. 

Each  color  value  is  a 4-byte  integer,  with  a value  of 

(R  * 65536)  + (G  * 256)  + B 

where: 

R is  red  intensity  value 
G is  green  intensity  value 
B is  blue  intensity  value. 

There  are  8 bits  for  each  primary;  the  maximum  intensity  for  each  primary  is  255. 
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Returns 

Success  indicator: 

TRUE  Successful  completion 
FALSE  Error  occurred. 


Possible  returns  from  WinGetLastError 


PMERRINVALIDHWND 

PMERRINVALIDFLAG 


An  invalid  window  handle  was  specified. 

An  invalid  bit  was  set  for  a parameter.  Use  constants 
defined  by  PM  for  options,  and  do  not  set  any  reserved 
bits. 


PMERR_PARAMETER_OUT_OF_RANGE  The  value  of  a parameter  was  not  within  the  defined  valid 

range  for  that  parameter. 


Remarks 

This  function  sends  all  main  windows  in  the  system  a WM_SYSCOLORCHANGE  message  to  indicate 
that  the  colors  have  changed.  When  this  message  is  received,  applications  that  depend  on  the 
system  colors  can  query  the  new  color  values  with  the  WinQuerySysColor  function. 

After  the  WM_SYSCOLORCHANGE  messages  are  sent,  all  windows  in  the  system  are  invalidated  so 
that  they  are  redrawn  with  the  new  system  colors. 

This  function  does  not  write  any  system  color  changes  to  the  initialization  file.  See  Appendix  G. 

The  following  table  gives  the  default  RGB  values  for  each  color  index: 


System  Color  Index 

Default  Color 

Default  RGB  Values 

SYSCLR_ACTIVEBORDER 

Pale  yellow 

255 

255 

128 

SYSCLR_ACTIVETITLE 

Teal 

64 

128 

128 

SYSCLR_ACTIVETITLETEXT 

White 

255 

255 

255 

SYSCLR_ACTIVETITLETEXTBGND 

Teal 

64 

128 

128 

SYSCLR_APPWORKSPACE 

Off-white 

255 

255 

224 

SYSCLR_BACKGROUND 

Light  gray 

204 

204 

204 

SYSCLR_BUTTONDARK 

Dark  gray 

128 

128 

128 

SYSCLR_BUTTONDEFAULT 

Black 

0 

0 

0 

SYSCLR_BUTTONLIGHT 

White 

255 

255 

255 

SYSCLR_BUTTONMIDDLE 

Light  gray 

204 

204 

204 

SYSCLR_DIALOGBACKGROUND 

Light  gray 

204 

204 

204 

SYSCLR_ENTRYFIELD 

Pale  yellow 

255 

255 

204 

SYSCLR_FIELDBACKGROUND 

Light  gray 

204 

204 

204 

SYSCLR_HELPBACKGROUND 

White 

255 

255 

255 

SYSCLR_HELPHILITE 

Blue  green 

0 

128 

128 

SYSCLR_HELPTEXT 

Dark  blue 

0 

0 

128 

SYSCLR_HILITEBACKGROUND 

Dark  gray 

128 

128 

128 

SYSCLR_HILITEFOREGROUND 

White 

255 

255 

255 

SYSCLRJCONTEXT 

Black 

0 

0 

0 
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System  Color  Index 

Default  Color 

Default  RGB  Values 

SYSCLRJNACTIVEBORDER 

Light  gray 

204 

204 

204 

SYSCLRJNACTIVETITLE 

Light  gray 

204 

204 

204 

SYSCLRJNACTIVETITLETEXT 

Dark  gray 

128 

128 

128 

SYSCLRJNACTIVETITLETEXTBGND 

Light  gray 

204 

204 

204 

SYSCLR_MENU 

Light  gray 

204 

204 

204 

SYSCLR_MENUDISABLEDTEXT 

Dark  gray 

128 

128 

128 

SYSCLR_MENUHILITE 

Black 

0 

0 

0 

SYSCLR_MENUHILITEBGND 

Light  grey 

204 

204 

204 

SYSCLR_MENUTEXT 

Black 

0 

0 

0 

SYSCLR_OUTPUTTEXT 

Black 

0 

0 

0 

SYSCLR_PAGEBACKGROUND 

White 

255 

255 

255 

SYSCLR_SCROLLBAR 

Pale  gray 

192 

192 

192 

SYSCLR_SHADOW 

Dark  gray 

128 

128 

128 

SYSCLR_SHADOWHILITEBGND 

Dark  gray 

128 

128 

128 

SYSCLR_SHADOWHILITEFGND 

White 

255 

255 

255 

SYSCLR_SHADOWTEXT 

Dark  gray 

128 

128 

128 

SYSCLR_TITLE  BOTT  OM 

Dark  gray 

128 

128 

128 

SYSCLR_TITLETEXT 

White 

255 

255 

255 

SYSCLR_WINDOW 

White 

255 

255 

255 

S Y SCLR_W  1 NDOWFR  A M E 

Dark  gray 

128 

128 

128 

S Y SCLR_W  1 NDOWST  ATICTEXT 

Blue 

0 

0 

128 

S Y SCLR_W  INDOWTEXT 

Black 

0 

0 

0 

Related  Functions 

• WinQuerySysColor 

Related  Messages 

• WMSYSCOLORCHANGE 
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Example  Code 

This  example  changes  the  desktop  background  to  blue  and  the  output  text  to  green. 

fdefine  INCL_WINSYS 
fdefine  INCL_GPILOGCOLORTABLE 
finclude  <0S2.H> 

typedef  struct  { 

LONG  index; 

LONG  color; 

} ENTRY; 

LONG  R,  G ,B; 

ENTRY  al Table [2];  /*  array  of  two  color/index  entries.  */ 

R = 5L;  G = 5L;  B = 200L; 

alTable[0]. index  = (R  * 65536L)  + (G  * 256L)  + B; 

R = 5;  G = 200;  B = 5; 

alTabl e[l] . index  = (R  * 65536L)  + (G  * 256L)  + B; 
alTable[0] .color  = SYSCLR_OUTPUTTEXT;  /*  output  text.  */ 
alTabl e[l] .color  = SYSCLR_BACKGROUND;  /*  desktop  background.  */ 

WinSetSysColors  (HWN0_DESKT0P, 

LCOL_RESET, 


LCOLF_INDRGB, 


OL, 

(UL0NG)4, 

( PL0NG)&al Tabl e [0] . i ndex) ; 


/*  reset  system  colors  before  */ 
/*  processing  remainder  of  this  */ 
/*  call.  */ 
/*  Array  of  (index, RGB)  */ 

/*  values.  Each  pair  of  */ 


/*  entries  is  8 bytes  */ 

/*  long,  comprising  4 */ 

/*  bytes  for  the  index,  */ 

/*  and  4 bytes  for  the  */ 

/*  color  value.  For  */ 

/*  system  color  indexes,*/ 

/*  see  1 Start.  */ 

/*  not  applicable.  */ 
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#define  INCL_WINWINDOWMGR  /*  Or  use  INCL_WIN  or  INCL_PM  */ 


BOOL  WinSetSysModalWindow  (HWND  hwndDesktop,  HWND  hwnd) 


This  function  makes  a window  become  the  system-modal  window,  or  ends  the  system-modal  state. 

Parameters 

hwndDesktop  (HWND)  - input 

Desktop- window  handle,  or  HWND_DESKTOP. 

hwnd  (HWND)  - input 

Handle  of  window  to  become  system-modal  window. 

If  NULLHANDLE,  system-modal  state  is  ended,  and  input  processing  returns  to  its  normal  state. 


Returns 

Success  indicator: 

TRUE  Successful  completion 
FALSE  Error  occurred. 

Possible  returns  from  WinGetLastError 

PMERR  INVALID  HWND  An  invalid  window  handle  was  specified. 

Remarks 

Input  processing  can  enter  a “system  modal”  state.  In  this  state,  all  pointing  device  and  keyboard 
input  is  directed  to  a special  window,  known  as  the  system-modal  window,  or  to  one  of  its  child 
windows  (or  a window  owned  by  one  of  them).  An  “owned"  window  is  a window  that  refers  to  its 
owner  window  set  by  using  either  the  hwndOwner  parameter  of  the  WinCreateWindow  function  or  the 
hwndNewOwner  parameter  of  the  WinSetOwner  function.  All  other. main  windows  behave  as  though 
they  are  disabled  and  no  interaction  is  possible  with  them. 

Note:  The  disabled  windows  are  not  actually  disabled,  but  made  noninteractive.  No  messages  are 
sent  to  these  windows  when  the  system-modal  state  is  entered  or  left,  and  their  WS_DISABLE 
style  bits  are  not  changed. 

Where  a system-modal  window  exists  and  another  window  is  explicitly  made  the  active  window,  the 
newly  activated  window  becomes  the  system-modal  window.  This  replaces  the  old  one,  which 
becomes  a noninteractive  window.  When  the  system-modal  window  is  destroyed,  the  system-modal 
state  is  ended,  and  input  processing  returns  to  its  normal  state. 

This  function  should  only  be  called  while  processing  pointing  device  or  keyboard  input. 

The  new  system-modal  window  is  not  locked  during  the  processing  of  this  function. 


Related  Functions 

• WinQuerySysModalWindow 
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Example  Code 

This  example  uses  the  WinSetModalWindow  to  set  a system  modal  window. 

Idefine  INCL_WINWINDOWMGR 
linclude  <0S2.H> 

HWND  hwndSysModal ; 

/*  Input  processing  can  enter  a "system  modal"  state.  In  */ 

/*  this  state,  all  pointing  device  and  keyboard  input  */ 

/*  is  directed  to  a special  window,  known  as  the  */ 

/*  system-modal  window.  Typically,  this  will  be  a dialog  */ 

/*  window  requiring  input.  */ 

WinSetSysModalWindow(HWND_DESKTOP, hwndSysModal ) ; 
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#define  INCL_WINSYS  /*  Or  use  INCL_WIN  or  INCL_PM  */ 


BOOL  WinSetSysValue  (HWND  hwndDeskTop,  LONG  IValueld,  LONG  IValue) 


This  function  sets  a system  value. 

Parameters 

hwndDeskTop  (HWND)  - input 
Desktop-window  handle: 

HWND_DESKTOP  Set  the  system  values  for  the  desktop-window  handle 

Other  Set  the  system  values  for  the  specified  desktop- window  handle. 

IValueld  (LONG)  - input 
System-value  identity. 

This  must  be  a valid  SV_*  value  (see  WinQuerySysValue).  The  following  values  can  be  set: 

SV_CXSIZEBORDER 

Width  of  the  sizing  border 

SV_CYSIZEBORDER 

Height  of  the  sizing  border 

SV_SWAPBUTTON 

TRUE  when  the  mouse  buttons  are  set  for  left-handed  use 

SV_CURSORRATE 

Cursor  blink  rate,  in  milliseconds 

SV_DBLCLKTIME 

Mouse  double-click  time,  in  milliseconds 

SV_CXDBLCLK 

Width  of  the  mouse  double-click  sensitive  area 

SV_CYDBLCLK 

Height  of  the  mouse  double-click  sensitive  area 

SV_ALARM 

TRUE  enables  the  alarm  sound  generated  by  WinAlarm;  FALSE  disables  the  alarm  sound 

SV_WARNINGFREQ 

Frequency  for  warning  alarms  generated  by  WinAlarm 

SVJWARNINGDURATION 

Duration  of  warning  alarms  generated  by  WinAlarm 

SV_NOTEFREQ 

Frequency  for  note  alarms  generated  by  WinAlarm 

SV_NOTEDURATION 

Duration  for  note  alarms  generated  by  WinAlarm 

SV_ERRORFREQ 

Frequency  for  error  alarms  generated  by  WinAlarm 

SV_ERRORDURATION 

Duration  for  error  alarms  generated  by  WinAlarm 

SV_FIRSTSCROLLRATE 

Delay  (in  milliseconds)  before  autoscrolling  starts,  when  using  a scroll  bar 
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SV_SCROLLRATE 

Delay  (in  milliseconds)  between  scroll  operations,  when  using  a scroll  bar 

SV_SETLIGHTS 

When  TRUE,  the  appropriate  light  is  set  when  the  keyboard  state  table  is  set. 

SVJNSERTMODE 

When  TRUE,  the  system  is  in  insert  mode. 

SV_MENUROLLDOWNDELAY 

Delay  in  milliseconds  before  displaying  a pulldown  referred  to  from  a submenu  item,  when  the 
button  is  already  down  as  the  pointer  moves  onto  the  submenu  item. 

SV_MENUROLLUPDELAY 

Delay  in  milliseconds  before  hiding  a pulldown  referred  to  from  a submenu  item,  when  the 
button  is  already  down  as  the  pointer  moves  off  the  submenu  item. 

SV_PRINTSCREEN 

TRUE  when  the  Print  Screen  function  is  enabled;  FALSE  when  the  Print  Screen  function  is 
disabled. 

IValue  (LONG)  - input 
The  system  value. 

Dimensions  are  in  pels  and  times  are  in  milliseconds. 


Returns 

Value-set  indicator: 

TRUE  System  value  set 
FALSE  An  error  occurred. 

Possible  returns  from  WinGetLastError 

PMERR  INVALID  HWND  An  invalid  window  handle  was  specified. 

PMERR_PARAMETER_OUT_OF_RANGE  The  value  of  a parameter  was  not  within  the  defined  valid 

range  for  that  parameter. 


Related  Functions 

• WinQuerySysValue 


Example  Code 

This  example  uses  the  WinSetSysValue  call  change  the  sizing  border  dimensions. 

Idefine  INCL_WINSYS 
linclude  <0S2.H> 

LONG  vIXBorder,  vlYBorder; 

vlXBorder  = WinSetSysValue(HWND_DESKTOP, 

SV_CXSIZEBORDER, 

20L); 

vlYBorder  = WinSetSysValue(HWND_DESKTOP, 

SV_CYSIZEBORDER, 

20L); 
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#define  INCL_WINWINDOWMGR  /*  Or  use  INCL_WIN  or  INCL_PM  */ 


BOOL  WinSetWindowBits  (HWND  hwnd,  LONG  lb,  ULONG  fIData,  ULONG  fIMask) 


This  function  sets  a number  of  bits  into  the  memory  of  the  reserved  window  words. 


Parameters 

hwnd  (HWND)  - input 
Window  handle. 

lb  (LONG)  - input 

Zero-based  index  of  the  value  to  be  set. 

The  units  of  b are  bytes.  Valid  values  are  zero  through  ( usExtra  —4),  where  usExtra  is  the 
parameter  in  WinRegisterClass  that  specifies  the  number  of  bytes  available  for 
application-defined  storage.  Any  of  the  QWL_*  values  specified  for  the  WinQueryWindowULong 
function  can  also  be  used. 

fIData  (ULONG)  - input 

Bit  data  to  store  in  the  window  words. 

This  is  done  under  the  control  of  the  fIMask  parameter. 

fIMask  (ULONG)  - input 

Bits  to  be  written  indicator. 

A “1"  bit  indicates  that  the  corresponding  bit  of  the  fIData  parameter  is  to  be  stored  into  the 
window  word.  A “0”  bit  indicates  that  the  corresponding  bit  of  the  fIData  parameter  is  to  be 
ignored  in  the  storing  operation;  the  value  of  that  bit  position  in  the  window  word  is  unaltered. 


Returns 

Success  indicator: 

TRUE  Successful  completion 
FALSE  Error  occurred. 

Remarks 

The  bits  are  set  in  a single  operation. 


Related  Functions 

• WinQueryWindowPtr 

• WinQueryWindowULong 

• WinQueryWindowUShort 

• WinSetWindowPtr 

• WinSetWindowULong 

• WinSetWindowUShort 
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Example  Code 

This  example  uses  the  WinSetWindowBits  call  to  change  the  attributes  of  a list  box  so  that  only  one 
item  can  be  be  selected.  This  is  done  by  turning  off  the  multiple-select  bit. 

fdefine  INCL_WINSYS 
finclude  <0S2.H> 

HWND  hwndMessageLB; 

WinSetWindowBits(hwndMessageLB, 

QWL_STYLE,  /*  change  style  bit.  */ 

0L,  /*  set  to  0.  */ 

LS_MULTIPLESEL);  /*  multiple  select  bit.  */ 
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#define  INCLJVINWINDOWMGR  /*  Or  use  INCL_WIN  or  INCL_PM  */ 

BOOL  WinSetWindowPos  (HWNO  hwnd,  HWND  hwndBehlnd,  LONG  lx,  LONG  ly,  LONG  lex, 

LONG  Icy,  ULONG  flOptlons) 

This  function  allows  the  general  positioning  of  a window. 

Parameters 

hwnd  (HWND)  - input 
Window  handle. 

hwndBehlnd  (HWND)  - input 

Relative  window-placement  order. 

Ignored  if  SWP_ZORDER  is  not  selected.  Values  that  can  be  specified  are: 

HWND_TOP  Place  hwnd  on  top  of  all  siblings 

HWND_BOTTOM  Place  hwnd  behind  all  siblings 

Other  Identifies  the  sibling  window  behind  which  hwnd  is  to  be  placed. 

lx  (LONG)  - input 

Window  position,  x-coordinate. 

This  is  the  x-coordinate  of  hwnd.  It  is  in  window  coordinates  relative  to  the  bottom  left  corner  of 
its  parent,  but  is  ignored  if  SWP_MOVE  is  not  selected. 

ly  (LONG)  - input 

Window  position,  y-coordinate. 

This  is  the  y-coordinate  of  hwnd.  It  is  in  window  coordinates  relative  to  the  bottom  left  corner  of 
its  parent,  but  is  ignored  if  SWP_MOVE  is  not  selected. 

lex  (LONG)  - input 
Window  size. 

This  specifies  the  width  of  hwnd  in  device  units,  but  is  ignored  if  SWP_SIZE  is  not  selected. 

Icy  (LONG)  - input 
Window  size. 

This  specifies  the  depth  of  hwnd  in  device  units,  but  is  ignored  if  SWP_SIZE  is  not  selected. 

flOptlons  (ULONG)  - input 

Window-positioning  options. 

One  or  more  of  these  options  can  be  specified: 

SWP_SIZE  Change  the  window  size. 

SWP_MOVE  Change  the  window  x,y  position. 

SWP_ZORDER  Change  the  relative  window  placement. 

SWP_SHOW  Show  the  window. 

SWP_HIDE  Hide  the  window. 

SWP_NOREDRAW  Changes  are  not  redrawn. 

SWP_NOADJUST  Do  not  send  a WM_ADJUSTWINDOWPOS  message  before  moving  or 
sizing. 
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SWP_ACTIVATE  Activate  the  hwnd  window  if  it  is  a frame  window.  This  indicator  has  no 
effect  on  other  windows. 

The  frame  window  is  made  the  topmost  window,  unless  SWP_ZORDER  is 
specified  also  in  which  instance  the  hwndBehind  window  is  used. 

SWP_DEACTIVATE  Deactivate  the  hwnd  window  if  it  is  a frame  window.  This  indicator  has  no 
effect  on  other  windows. 


SWP_MINIMIZE 


SWPMAXIMIZE 


SWPRESTORE 


The  frame  window  is  made  the  bottommost  window,  unless  SWP_ZORDER 
is  specified,  in  which  instance  the  hwndBehind  window  is  used. 

Minimize  the  window.  This  indicator  has  no  effect  if  the  window  is  in  a 
minimized  state,  and  is  also  mutually  exclusive  with  SWP_MAXIMIZE  and 
SWP_RESTORE. 

Maximize  the  window.  This  indicator  has  no  effect  if  the  window  is  in  a 
maximized  state,  and  is  also  mutually  exclusive  with  SWP_MINIMIZE  and 
SWP_RESTORE. 

Restore  the  window.  This  indicator  has  no  effect  if  the  window  is  in  its 
normal  state,  and  is  also  mutually  exclusive  with  SWP_MINIMIZE  and 
SWP_MAXIMIZE. 

The  position  and  size  of  the  window  in  its  normal  state  is  remembered  in 
its  window  words  when  it  is  first  maximized  or  minimized,  although  these 
values  can  be  altered  by  use  of  the  WinSetWindowUShort  function. 

The  window  is  restored  to  the  position  and  size  remembered  in  its  window 
words,  unless  the  SWP_MOVE  or  SWP_SIZE  indicators  are  set.  These 
indicators  cause  the  position  and  size  values  specified  in  this  function  to 
be  used. 


Returns 

Repositioning  indicator: 

TRUE  Window  successfully  repositioned 
FALSE  Window  not  successfully  repositioned. 

Possible  returns  from  WinGetLastError 

PMERR  INVALID  HWND  An  invalid  window  handle  was  specified. 

PMERR_INVALID_FLAG  An  invalid  bit  was  set  for  a parameter.  Use  constants 

defined  by  PM  for  options,  and  do  not  set  any  reserved 
bits. 


Remarks 

Note:  Messages  may  be  received  from  other  processes  or  threads  during  the  processing  of  this 
function. 

If  a window  created  with  the  CS_SAVEBITS  style  is  reduced,  the  screen  image  saved  is  used  to 
redraw  the  area  uncovered  when  the  window  size  changes,  if  those  bits  are  still  valid. 

If  the  CS_SIZEREDRAW  style  is  present,  the  entire  window  area  is  assumed  invalid  if  sized. 
Otherwise,  WM_CALCVALIDRECTS  is  sent  to  the  window  to  inform  the  window  manager  which  bits  it 
may  be  possible  to  preserve. 

Messages  sent  from  WinSetWindowPos  and  WinSetMultWindowPos  have  specific  orderings  within 
the  window-positioning  process.  The  process  begins  with  redundancy  checks  and  precalculations  on 
every  window  for  each  requested  operation.  For  example,  if  SWP_SHOW  is  present  but  the  window 
is  already  visible,  SWP_SHOW  is  turned  off.  If  SWP_SIZE  is  present,  and  the  new  size  is  equal  to  the 
old  size,  SWP_SIZE  is  turned  off. 
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WinSetWindowPos  - 
Set  Window  Position 


If  the  operations  create  new  results,  the  information  is  calculated  and  stored  (for  instance,  when 
sizing  or  moving,  the  new  window  rectangle  is  stored  for  later  use).  It  is  at  this  point  that  the 
WM_ADJUSTWINDOWPOS  message  is  sent  to  any  window  that  is  sizing  or  moving.  It  is  also  at  this 
point  that  the  WM_CALCVALIDRECTS  message  is  sent  to  any  window  that  is  sizing  and  does  not 
have  the  CS_SIZEREDRAW  window  style. 

When  all  the  new  window  states  are  calculated,  the  window-management  process  begins.  Window 
areas  that  can  be  preserved  are  moved  from  the  old  to  the  new  positions,  window  areas  that  are 
invalidated  by  these  operations  are  calculated  and  distributed  as  update  regions.  When  this  is 
finished,  and  before  any  synchronous-paint  windows  are  repainted,  the  WM_SIZE  message  is  sent  to 
any  windows  that  have  changed  size.  Next,  all  the  synchronous-paint  windows  that  can  be  are 
repainted,  and  the  process  is  complete. 

If  a synchronous-paint  parent  window  has  a size-sensitive  area  displayed  that  includes 
synchronous-paint  child  windows,  the  parent  needs  to  reposition  those  windows  when  it  receives  the 
WM_SIZE  message.  Their  invalid  regions  are  added  to  the  parent’s  invalid  region,  resulting  in  one 
update  after  the  parent’s  WM_SIZE  message,  rather  than  many  independent  (and  later,  duplicated) 
updates. 

Note:  Some  windows  will  not  be  positioned  precisely  to  the  parameters  of  this  function,  but 

according  to  the  behavior  of  their  window  procedure.  For  example,  frame  windows  without  a 
style  creation  flag  of  FCF_NOBYTEALIGN  will  not  position  to  any  specific  screen  coordinate. 
Similarly,  frame  windows  with  zero  size  and  position  are  created  by  the  WinCreateStdWindow 
function  and  therefore  these  values  are  treated  as  a special  case  by  the  frame  window 
procedure. 


Messages  sent  by  this  function  are: 


WM_CALCVALIDRECTS 

WMSIZE 

WMMOVE 

WM_ACTIVATE 

WMADJUSTWINDOWPOS 


Sent  to  determine  the  area  of  a window  that  may  be  possible  to  preserve 
as  the  window  is  sized. 

Sent  if  the  size  of  the  window  has  changed,  after  the  change  has  been 
made. 

Sent  when  a window  with  CS_MOVENOTIFY  class  style  moves  its 
absolute  position. 

Sent  if  a different  window  becomes  the  active  window.  See  also 
W i nSet  ActiveWi  ndo  w. 

Not  sent  if  SWP_NOADJUST  is  specified.  The  message  contains  an  SWP 
structure  that  has  been  filled  in  by  this  function  with  the  proposed 
move/size  data.  The  window  can  adjust  this  new  position  by  changing 
the  contents  of  the  SWP  structure.  If  hwnd  specifies  a frame  window, 
this  function  recalculates  the  sizes  and  positions  of  the  frame  controls. 

If  the  new  window  rectangle  for  any  frame  control  is  empty,  instead  of 
resizing  or  repositioning  that  control,  it  is  hidden  if  SWP_HIDE  is 
specified.  This  eliminates  needless  processing  of  windows  that  are  not 
visible.  The  window  rectangle  of  the  control  in  question  is  left  in  its 
original  state.  For  example,  if  WinSetWindowPos  is  issued  to  change  the 
size  of  a standard-frame  window  to  an  empty  rectangle,  and 
WinQueryWindowRect  is  issued  against  the  client  window,  the  rectangle 
returned  is  not  an  empty  rectangle,  but  the  original  client  rectangle 
before  WinSetWindowPos  was  issued. 


Related  Functions 

• WinGetMinPosition 

• WinQueryActiveWindow 

• WinQueryWindowPos 

• WinSaveWindowPos 

• WinSetActiveWindow 

• WinSetMultWindowPos 
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WinSetWindowPos  - 
Set  Window  Position 


Related  Messages 

• WM_ACTIVATE 

• WM_ADJUSTWINDOWPOS 

• WM_CALCVALIDRECTS 

• WM_ERASEBACKGROUND 

• WM_MOVE 

• WM  SIZE 


Example  Code 

This  example  uses  the  recommended  size,  position  and  status  from  the  WinQueryTaskSize  call  to 
position  the  first  window  of  a newly-started  application  (typically  the  main  window). 

Idefine  INCL_WINSWITCHLIST 
fdefine  INCL_WINFRAMEMGR 
linclude  <0S2.H> 

HAB  hab; 

SWP  winpos; 

HWND  hwndFrame; 


WinQueryTaskSizePos(hab, 


0, 

&wi npos) ; 


Wi  nSetWi ndowPos (hwndFrame , HWND_T0P , 


winpos.x, 

/*  x pos  */ 

winpos.y, 

/*  y pos  */ 

winpos.cx, 

/*  x size  */ 

wi  npos.cy, 

/*  y size  */ 

SWP_ACTIVATE  | SWP_M0VE  | 

| SWP_SIZE  | SWP_SH0W) ; /*  flags*/ 
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WinSetWindowPtr  - 
Set  Window  Words  Pointer 


#define  INCL_WINWINDOWMGR  /*  Or  use  INCL_WIN  or  INCL_PM  7 


BOOL  WinSetWindowPtr  (HWND  hwnd,  LONG  lb,  PVOID  pp) 


This  function  sets  a pointer  value  into  the  memory  of  the  reserved  window  words. 


Parameters 

hwnd  (HWND)  - input 
Window  handle. 

lb  (LONG)  - input 

Zero-based  index  into  the  window  words. 

The  units  of  b are  bytes.  Valid  values  are  zero  through  ( usExtra  —4),  where  usExtra  is  the 
parameter  in  WinRegisterClass  that  specifies  the  number  of  bytes  available  for 
application-defined  storage. 

The  value  QWP_PFNWP  can  be  used  as  the  index  for  the  address  of  the  window  procedure  for 
the  window. 

pp  (PVOID)  - input 

Pointer  value  to  store  in  the  window  words. 


Returns 

Success  indicator: 

TRUE  Successful  completion 
FALSE  Error  occurred. 

An  invalid  window  handle  was  specified. 

The  value  of  a parameter  was  not  within  the  defined  valid 
range  for  that  parameter. 


Possible  returns  from  WinGetLastError 

PMERRINVALIDHWND 

PMERRPARAMETEROUTOFRANGE 


Related  Functions 

• WinQueryWindowPtr 

• WinQueryWindowULong 

• WinQueryWindowUShort 

• WinSetWindowBits 

• WinSetWindowULong 

• WinSetWindowUShort 
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WinSetWindowPtr  - 
Set  Window  Words  Pointer 


Example  Code 

This  function  retrieves  a pointer  value  from  the  memory  of  the  reserved  window  word. 


MyWindowProc(HWND  hwnd,  ULONG  msg,  MPARAM  mpl,  MPARAM  mp2) 

{ 

MYINSTANCEDATA  *InstanceData;  /*  application  defined  structure  */ 

switch  (msg)  { 
case  WM_CREATE : 

DosAl 1 ocMem(&InstanceData , si zeof (MYINSTANCEDATA) , fALLOC) ; 

/*  WindowProcedure  initializes  instance  data  for  this  window  */ 


/*  set  pointer  to  instance  in  window  words  */ 
WinSetWindowPtr (hwnd,  0,  InstanceData) ; 
break; 

case  WMJJSER  + 1:  /*  application  defined  message  */ 

/*  Window  procedure  retrieves  instance  data  to  */ 
/*  process  this  message  */ 

InstanceData  = WinQueryWindowPtr(hwnd,  0); 


break; 
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WinSetWindowText 
Set  Window  Text 


#define  INCLJVINWINDOWMGR  /*  Or  use  INCL_WIN  or  INCL_PM  */ 


BOOL  WinSetWindowText  (HWND  hwnd,  PSZ  pszStrlng) 


This  function  sets  the  window  text  for  a specified  window. 

Parameters 

hwnd  (HWND)  - input 
Window  handle. 

pszStrlng  (PSZ)  - input 
Window  text. 


Returns 

Success  indicator: 

TRUE  Text  updated 
FALSE  Error  occurred. 

Possible  returns  from  WinGetLastError 

PMERR  INVALID  HWND  An  invalid  window  handle  was  specified. 

Remarks 

This  function  sends  a WM_SETWINDOWPARAMS  message  to  the  window  identified  by  hwnd. 

If  this  function  references  the  window  of  another  process,  pszString  must  be  in  memory  that  is 
shared  by  both  processes:  otherwise,  a memory  error  may  occur. 

If  hwnd  has  a style  of  WS_FRAME,  the  title-bar  window  text  is  set. 

Some  window  classes  interpret  the  pszString  in  a special  way.  The  tilde  character  (~)  indicates  that 
the  following  character  is  a mnemonic;  for  details,  see  Chapter  13,  “Button  Control  Window 
Processing”  on  page  13-1  and  Chapter  17,  "Menu  Control  Window  Processing”  on  page  17-1. 


Related  Functions 

• WinQueryDIgltemShort 

• WinQueryDIgltemText 

• WinQueryDIgltemTextLength 

• WinQueryWindowText 

• WinQueryWindowTextLength 

• WinSetDIgltemShort 

• WinSetDIgltemText 

Related  Messages 

• WM_SETWINDOWPARAMS 
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WinSetWindowText  - 
Set  Window  Text 


Example  Code 

This  example  calls  WinQuerySessionTitle  to  retrieve  the  application's  title,  and  then  sets  the  title  bar 
of  the  frame  window  to  that  title  with  WinSetWindowText. 

fdefine  INCL_WINMESSAGEMGR 
fdefine  INCL_WINWINDOWMGR 
finclude  <0S2.H> 

HAB  hab; 

HWND  hwndFrame,  hwndClient; 

CHAR  szTitle[MAXNAMEL  + 1]; 

WinQuerySessionTitle (hab, 

0,  szTitle, 
sizeof(szTitle)); 

hwndFrame  = WinQueryWindow(hwndClient, 

QW_PARENT);  /*  get  handle  of  parent,  */ 

/*  which  is  frame  window.  */ 

WinSetWindowText(hwndFrame,  szTitle) ; 
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WinSetWindowThunkProc  - 

Set  Window  Pointer-Conversion  Procedure 


#define  INCL_WINTHUNKAPI  /*  Or  use  INCL_WIN  or  INCL_PM  7 


BOOL  WinSetWindowThunkProc  (HWND  hwnd,  PFN  pthunkpr) 


This  function  associates  a pointer-conversion  procedure  with  a window. 

Parameters 

hwnd  (HWND)  - input 
Window  handle. 

pthunkpr  (PFN)  - input 

Pointer-conversion  procedure  identifier: 

NULL  Any  existing  pointer-conversion  procedure  is  dissociated  from  this  window. 
Other  The  pointer-conversion  procedure  to  be  associated  with  this  window. 

Returns 

Success  indicator: 

TRUE  Successful  completion 
FALSE  An  error  occurred. 

Related  Functions 

• WinQueryClassThunkProc 

• WinQueryWindowModel 

• WinQueryWindowThunkProc 

• WinSetClassThunkProc 

Example  Code 

In  this  example,  any  thunking  procedure  is  dissociated  from  the  window. 

Idefine  INCL_WINTHUNKAPI 
linclude  <0S2.H> 

HWND  hwnd; 


Wi nSetWi ndowThunkProc (hwnd , NULL) ; 
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WinSetWindowULong  - 
Set  Window  Word  Long 


#define  INCL_WINWINDOWMGR  /*  Or  use  INCL_WIN  or  INCL_PM  */ 


BOOL  WinSetWindowULong  (HWND  hwnd,  LONG  lb,  ULONG  uIData) 


This  function  sets  an  unsigned,  long  integer  value  into  the  memory  of  the  reserved  window  words. 


Parameters 

hwnd  (HWND)  - input 
Window  handle. 

lb  (LONG)  - input 

Zero-based  index  of  the  value  to  be  set. 

The  units  of  lb  are  bytes.  Valid  values  are  zero  through  ( usExtra  —4),  where  usExtra  is  the 
parameter  in  WinRegisterClass  that  specifies  the  number  of  bytes  available  for 
application-defined  storage.  So  too  are  any  of  the  QWL_*  values,  as  specified  for  the 
WinQueryWindowULong  function. 

QWS_*  values  cannot  be  used. 

uIData  (ULQNG)  - input 

Unsigned,  long  integer  value  to  store  in  the  window  words. 


Returns 

Success  indicator: 

TRUE  Successful  completion 
FALSE  Error  occurred. 

Possible  returns  from  WinGetLastError 

PMERRINVALID  HWND  An  invalid  window  handle  was  specified. 

PMERR_PARAMETER_OUT_OF_RANGE  The  value  of  a parameter  was  not  within  the  defined  valid 

range  for  that  parameter. 


Remarks 

The  specified  lb  is  valid  only  if  all  of  the  bytes  referenced  are  within  the  reserved  memory. 


Related  Functions 

• WinQueryWindowPtr 

• WinQueryWindowULong 

• WinQueryWindowUShort 

• WinSetWindowBits 

• WinSetWindowPtr 

• WinSetWindowUShort 
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WinSetWindowULong  * 
Set  Window  Word  Long 


Example  Code 

This  example  transfers  a pointer  from  the  application-defined  data  area  of  a dialog  window  to  the 
application-defined  data  area  (window  word)  of  a main  window.  The  pointer  is  then  retrieved. 

fdefine  INCL.WINWINDOWMGR 
finclude  <0S2.H> 

HWND  hwndCl ient; 

ULONG  msg; 

MPARAM  pPann,  mpl,  mp2; 

/*  inside  dialog  procedure.  */ 
switch ( msg  ) 

{ 

case  WM_INITDLG: 

pParm  = (MPARAM)mp2;  /*  This  points  to  the  data  */ 


/*  area  and  is  passed  by  */ 

/*  the  WinLoadDlg,  */ 

/*  WinCreateDlg,  and  */ 

/*  WinDlgBox  calls  in  their  */ 

/*  pCreateParams  */ 

/*  parameter.  */ 

WinSetWindowULong(hwndClient,  /*  place  pointer  in  window  */ 

QWLJJSER,  /*  word  area.  */ 

(ULONG)  pParm); 


case  WM_COMMAND: 

switch  ( SH0RT1FR0MMP(  mpl  ) ) 

{ 

case  DID_0K: 


} 


} 


/*  retrieve  pointer  from 
/*  window  word  area. 

pParm  = (MPARAM)WinQueryWindowULong(hwndClient, 

QWLJJSER) ; 


*/ 

*/ 
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WinSetWindowUShort  - 
Set  Window  Word  Short 


#define  INCL_WINWINDOWMGR  /*  Or  use  INCL_WIN  or  INCL_PM  */ 


BOOL  WinSetWindowUShort  (HWND  hwnd,  LONG  lb,  USHORT  usData) 


This  function  sets  an  unsigned,  short  integer  value  into  the  memory  of  the  reserved  window  words. 

Parameters 

hwnd  (HWND)  - input 
Window  handle. 

lb  (LONG)  - input 

Zero-based  index  of  the  value  to  be  set. 

The  units  of  lb  are  bytes.  Valid  values  are  zero  through  ( usExtra  —2),  where  usExtra  is  the 
parameter  in  WinRegisterClass  that  specifies  the  number  of  bytes  available  for 
application-defined  storage.  So  too  are  any  of  the  QWS_*  values,  as  specified  for  the 
WinQueryWindowUShort  function. 

QWL_*  values  cannot  be  used. 

usData  (USHORT)  - input 

Unsigned,  short  integer  value  to  store  in  the  window  words. 


Returns 

Success  indicator: 

TRUE  Successful  completion 
FALSE  Error  occurred. 

Related  Functions 

• WinQueryWindowPtr 

• WinQueryWindowULong 

• WinQueryWindowUShort 

• WinSetWindowBits 

• WinSetWindowPtr 

• WinSetWindowULong 

Example  Code 

This  example  changes  the  height  to  which  a window  is  restored  to  100  by  changing  the  value  of  a 
system  defined  window  word. 

Idefine  INCL_WINWINDOWMGR 
finclude  <0S2.H> 

HWND  hwnd; 

Wi nSetWi ndowUShort ( hwnd , 

QWS_CYREST0RE,  /*  The  height  to  which  */ 

/*  the  window  is  */ 

/*  restored.  */ 

(USHORT) 100); 
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WinShowCursor 
Show  Cursor 


#define  INCL_WINCURSORS  /*  Or  use  INCL_WIN  or  INCL_PM.  Also  in  COMMON  section  7 


BOOL  WinShowCursor  (HWND  hwnd,  BOOL  fShow) 


This  function  shows  or  hides  the  cursor  that  is  associated  with  a specified  window. 

Parameters 

hwnd  (HWND)  - input 

Handle  of  window  to  which  the  cursor  belongs. 

fShow  (BOOL)  - input 
Show  indicator: 

TRUE  Make  cursor  visible 

FALSE  Make  cursor  invisible. 

Returns 

Success  indicator: 

TRUE  Successful  completion 

FALSE  Error  occurred,  or  an  attempt  was  made  to  show  the  cursor  when  it  was  already 
visible. 

Possible  returns  from  WinGetLastError 

PMERRJNVALID  HWND  An  invalid  window  handle  was  specified. 

Remarks 

This  function  must  be  called  by  the  same  thread  that  created  the  cursor  that  is  affected. 

A cursor  show-level  count  is  maintained.  It  is  incremented  by  a hide  operation  and  decremented  by 
a show  operation.  The  cursor  is  actually  visible  if  the  cursor  show-level  count  is  zero,  otherwise  it  is 
invisible.  When  decrementing,  the  cursor  show-level  count  is  fixed  at  zero  so  as  not  to  show  the 
cursor  too  many  times,  but  it  is  possible  to  hide  the  cursor  a number  of  times  in  succession. 


Related  Functions 

• WinCreateCursor 

• WinDestroyCursor 

• WinQueryCursorlnfo 
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WinShowCursor  - 
Show  Cursor 


Example  Code 

This  example  shows  the  cursor  if  it  is  successfully  created. 

fdefine  INCL_WINCURSORS 
finclude  <0S2.H> 

HWND  hwnd;  /*  handle  of  window  that  has  pointer  captured  */ 
RECTL  rcl ; 


WinQueryWindowRect(hwnd,  &rcl); 

if  (WinCreateCursor(hwnd,  /*  This  must  be  the  handle  */ 

/*  of  a window  for  which  */ 


/*  the  application  can  */ 

/*  receive  input.  */ 

100,  /*  x.y  position  of  cursor.  */ 
100, 

5,  /*  cursor  width.  */ 

5,  /*  cursor  height.  */ 

CURSOR_FLASH, 

&rcl ) ) /*  region  where  the  cursor  */ 
/*  is  visible.  */ 

WinShowCursor(hwnd, 


TRUE);  /*  make  cursor  visible.  */ 
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WinShowPointer 
Show  Pointer 


#define  INCL_WINPOINTERS  /*  Or  use  INCL_WIN  or  INCL_PM  7 


BOOL  WinShowPointer  (HWND  hwndOeskTop,  BOOL  fShow) 


This  function  adjusts  the  pointer  display  level  to  show  or  hide  a pointer. 


Parameters 

hwndDeskTop  (HWNO)  - input 
Desktop-window  handle: 

HWND_DESKTOP  The  desktop-window  handle 

Other  The  specified  desktop-window  handle. 

fShow  (BOOL)  - input 
Level-update  indicator: 

TRUE  Decrement  pointer  display  level  by  one.  (The  pointer  level  is  not  decremented  to  a 
negative  value.) 

FALSE  Increment  pointer  display  level  by  one. 

Returns 

Display-level-updated  indicator: 

TRUE  Pointer  display  level  not  successfully  updated. 

FALSE  Pointer  display  level  successfully  updated 

Possible  returns  from  WinGetLastError 

PMERR  INVALID  HWND  An  invalid  window  handle  was  specified. 

Remarks 

The  pointer  display  level  determines  whether  the  pointer  is  shown.  If  it  is  zero,  the  pointer  is  visible, 
but  if  it  is  greater  than  zero,  the  pointer  is  not  visible.  The  initial  setting  of  the  pointer  display  level  is 
dependent  on  the  capabilities  of  the  device.  If  a pointing  device  exists,  the  initial  setting  of  the 
pointer  display  level  is  zero,  otherwise  it  is  one.  The  existing  pointer  display  level  can  be  obtained 
by  using  the  WinQuerySysValue  function  with  IValueid  set  to  SVPOINTERLEVEL. 


Related  Functions 

• WinCreatePointer 

• WinCreatePointerlndirect 

• Win  Destroy  Pointer 

• WinDrawPointer 

• WinLoadPointer 

• WinQueryPointer 

• WinQueryPointerlnfo 

• WinQueryPointerPos 

• WinQuerySysPointer 

• WinSetPointer 

• WinSetPointerPos 
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WinShowPointer  - 
Show  Pointer 


Example  Code 

This  example  obtains  the  pointer  handle  from  the  desktop  window  handle  and  hides  the  pointer. 

fdefine  INCL_WINPOINTERS 
Idefine  INCL_WINDESKTOP 
finclude  <0S2.H> 

HPOINTER  hpointer; 

HWND  hwnd; 

tipointer  = WinQueryPointer(HWND_DESKTOP) ; 

WinShowPointer(hwnd, FALSE) ; 
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WinShowTrackRect  - 
Show  Tracking  Rectangle 


#define  INCL_WINTRACKRECT  /*  Or  use  INCL_WIN  or  INCL_PM  */ 


BOOL  WinShowTrackRect  (HWNO  hwnd,  BOOL  fShow) 


This  function  hides  or  shows  the  tracking  rectangle. 


Parameters 

hwnd  (HWND)  - input 
Window  handle. 

Passed  to  the  WinTrackRect  function. 

fShow  (BOOL)  - input 
Show  indicator: 

TRUE  Show  the  tracking  rectangle 
FALSE  Hide  the  tracking  rectangle. 

Returns 

Success  indicator: 

TRUE  Successful  completion 
FALSE  Error  occurred. 

Possible  returns  from  WinGetLastError 

PMERRINVALIDHWND  An  invalid  window  handle  was  specified. 

Remarks 

This  function  maintains  a show  count.  When  a hide  request  is  made,  this  count  is  decremented; 
when  a show  request  is  made,  the  count  is  incremented.  When  the  count  makes  a transition  from  0 
to  —1,  the  rectangle  is  hidden;  when  the  count  makes  a transition  from  —1  to  0,  the  rectangle  is 
shown. 

When  a rectangle  is  tracking,  the  application  must  call  this  function  to  hide  the  rectangle  if  there  is  a 
possibility  of  corrupting  the  tracking  rectangle  while  drawing.  The  rectangle  is  shown  afterwards. 
Because  the  rcITrack  structure  is  updated  continuously,  the  application  can  examine  the  coordinates 
of  the  current  tracking  rectangle  to  determine  whether  temporary  hiding  is  necessary. 

The  only  case  where  an  application  needs  to  use  this  function  is  during  asynchronous  drawing.  If  an 
application  is  drawing  on  one  thread,  and  issuing  WinTrackRect  on  another,  unwanted  areas  of 
tracking  rectangle  may  be  left  behind.  The  drawing  thread  is  therefore  responsible  for  calling  this 
function  whenever  tracking  is  in  progress.  The  application  must  provide  for  communication  between 
the  two  threads  to  ensure  that  if  one  thread  is  tracking,  the  drawing  thread  issues  this  function.  This 
can  be  done  with  a semaphore. 


Related  Functions 

• WinTrackRect 
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WinShowWindow  - 
Show  Window 


#define  INCL_WINWINDOWMGR  /*  Or  use  INCL_WIN  or  INCL_PM.  Also  in  COMMON  section  7 


BOOL  WinShowWindow  (HWND  hwnd,  BOOL  fNewVIsIblllty) 


This  function  sets  the  visibility  state  of  a window. 


Parameters 

hwnd  (HWND)  - input 
Window  handle. 

fNewVisIbillty  (BOOL)  - input 
New  visibility  state: 

TRUE  Set  window  state  visible 

FALSE  Set  window  state  invisible. 

Returns 

Visibility  changed  indicator: 

TRUE  Window  visibility  successfully  changed 
FALSE  Window  visibility  not  successfully  changed. 

Possible  returns  from  WinGetLastError 

PMERR  INVALID  HWND  An  invalid  window  handle  was  specified. 

Remarks 

A window  possesses  a visibility  state  indicated  by  the  WS_VISIBLE  style  bit.  When  the  WS_VISIBLE 
style  bit  is  set,  the  window  is  shown  and  subsequent  drawing  into  the  window  is  presented,  unless 
that  window  is  obscured  by  some  other  window,  or  at  least  one  of  the  windows  upward  in  the  parent 
chain  from  hwnd  does  not  have  the  WS_VISIBLE  style. 

When  the  WS_VISIBLE  style  bit  is  not  set,  the  window  is  not  shown  (“hidden”)  and  subsequent 
drawing  into  the  window  is  not  presented,  even  if  that  window  is  not  obscured  by  another  window. 

If  the  value  of  the  WS_VISIBLE  style  bit  has  been  changed,  the  WM_SHOW  message  is  sent  to  the 
window  of  hwnd  before  the  function  returns. 

Related  Functions 

• WinBeginPaint 

• WinEnableWindowUpdate 

• WinEndPaint 

• WinExcludeUpdateRegion 

• WinGetClipPS 

• WinGetPS 

• WinGetScreenPS 

• WinlnvalidateRect 

• WinlnvalidateRegion 

• WinlsWindowShowing 

• WinlsWindowVisible 

• WinLockVisRegions 

• WinOpenWindowDC 

• WinQueryUpdateRect 

• WinQueryUpdateRegion 
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WinShowWindow  - 
Show  Window 


• WinRealizePalette 

• WinReleasePS 

• WinllpdateWindow 

• WinValidateRect 

• WinValidateRegion 


Related  Messages 

• WM_SHOW 


Example  Code 

This  example  uses  the  WinShowWindow  call  to  make  a modeless  dialog  window  visible. 

Idefine  INCLJ/INWINDOWMGR 
Idefine  I NCL_WINDI ALOGS 
linclude  <0S2.H> 

Idefine  DLG_MODELESS  900 

/*  dialog  procedure  declaration.  */ 

MRESULT  EXPENTRY  DlgProc(  HWND  hwndDlg,  ULONG  msg,  MPARAM  mpl,  MPARAM  mp2  ); 

HWND  hwnd; 

hwnd  = WinLoadDlg(  HWND_DESKTOP, 

HWND_OBJECT, 

(PFNWP)DlgProc, 

(HMODULE)NULL, 

DLG_MODELESS, 

NULL); 


/* 

DlgProc(  HWND  hwndDlg,  ULONG  msg,  MPARAM  mpl, 

MPARAM  mp2  ) 

{ 

CASE  USER_DEFINED: 

*/ 

WinShowWindow(  hwnd, 

TRUE  );  /*  show  window.  */ 

WinSetFocus(  HWND_DESKTOP,  hwnd  ); 

} 
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WinShutdownSystem  - 
Shutdown  System 


#define  INCL_WINWORKPLACE 


BOOL  WinShutdownSystem  (HAB  hab,  HMQ  hmq) 


The  WinShutdownSystem  function  will  close  down  the  system. 

Parameters 

hab  (HAB)  - input 

Anchor-block  handle, 
hmq  (HMQ)  - input 

Message-queue  handle. 

Returns 

Success  indicator: 

TRUE  Successful  completion 
FALSE  Error  occurred. 

Remarks 

The  WinShutdownSystem  function  will  close  all  running  applications  and  will  then  call  DosShutdown. 

Presentation  Manager  applications  will  receive  a WM_SAVEAPPLICATION  message  prior  to  a 
WM_QUIT  message. 

When  the  system  is  restarted,  all  applications  that  were  running  when  WinShutdownSystem  was  last 
called  will  be  restarted. 
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Window  Start  Application 


#define  INCL_WINWINDOWMGR  /*  Or  use  INCL_WIN  or  INCL_PM  */ 


HAPP  WinStartApp  (HWND  hwndNotlfy,  PPROGDETAILS  pDetalls,  PSZ  pszParams, 
PVOID  pReserved,  ULONG  ulOptlons) 


This  function  starts  an  application. 


Parameters 

hwndNotlfy  (HWND)  - input 
Notification-window  handle. 

A WM_APPTERMINATENOTIFY  message  is  posted  to  this  window,  when  the  started  application 
terminates. 

NULLHANDLE  Do  not  post  the  notification  message 

Other  Post  the  notification  message  to  this  window. 

pDetalls  (PPROGDETAILS)  - input 
Program  list  structure. 

pszParams  (PSZ)  - input 

Input  parameters  for  the  application  to  be  started. 

This  specifies  the  command  line  parameters  to  be  passed  to  this  application  when  it  starts. 

NULL  There  are  no  parameters  to  be  passed  to  the  application 

Other  The  parameters  to  be  passed  to  the  application. 

pReserved  (PVOID)  - input 
Start  data. 

Reserved,  must  be  NULL. 

ulOptlons  (ULONG)  - input 
Option  indicators. 

If  more  than  one  option  is  selected,  the  values  can  be  ORed  together. 

0 No  options  selected. 

SAFJNSTALLEDCMDLINE  The  command  line  parameters  installed  in  the  program  starter  list 

are  used;  the  pszParams  parameter  is  ignored. 

SAF_STARTCHILDAPP  The  specified  application  is  started  as  a child  session  of  the 

session  from  which  WinStartApp  is  issued.  The  calling  application 
may  terminate  the  called  application  with  a WinTerminateApp 
function. 
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WinStartApp  - 
Window  Start  Application 


Returns 

Application  handle. 

NULL  Application  not  started 
Other  Application  handle. 


Possible  returns  from  WinGetLastError 

PMERR  INVALID  PARAMETERS  An  application  parameter  value  is  invalid  for  its  converted 

PM  type.  For  example:  a 4-byte  value  outside  the  range 
—32,768  to  +32,767  cannot  be  converted  to  a SHORT,  and 
a negative  number  cannot  be  converted  to  a ULONG  or 
USHORT. 


PMERRINVALIDAPPL 

PMERR  JNVALIDWINDOW 

PMERRSTARTEDINBACKGROUND 

PMERRDOSERROR 


Attempted  to  start  an  application  whose  type  is  not 
recognized  by  OS/2. 

The  window  specified  with  a Window  List  function  is  not  a 
valid  frame  window. 

The  application  started  a new  session  in  the  background. 
A DOS  call  returned  an  error. 


Remarks 

Starts  the  application  identified  in  PROGDETAILS. 

If  the  application  is  successfully  started,  the  return  value  is  a handle  to  the  application.  If 
SAF_STARTCHILDAPP  is  specified,  this  can  be  used  to  stop  the  application  (see  the 
WinTerminateApp  function). 

When  the  program  specified  by  the  application  handle  terminates,  the  window  specified  by  the 
hwndNotify  parameter  (if  the  window  still  exists  and  is  valid)  has  a WM_APPTERMINATENOTIFY 
message  posted  to  it  to  notify  it  of  the  application  termination. 

This  function  requires  the  existence  of  a message  queue. 


Related  Functions 

• WinTerminateApp 

Related  Messages 

• WM_APPTERMINATENOTIFY 
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WinStartApp  - 
Window  Start  Application 

Example  Code 

This  example  calls  WinStartApp  in  a typical  termination  sequence. 

Idefine  INC1_D0SSESMGR 
finclude  <os2.h> 

HWND  hwndNotify; 

PPROGDETAILS  pDetails; 

HAPP  happ ; 

pDetai1s->Length  = sizeof(PROGDETAILS) ; 

pDetai1s->progt.progc  = PR0G_WIND0WABLEVI0; 
pDetai1s->progt.fbVisible  = SHE_VISIBLE; 
pDetails->pszTitle  = "TEXT"; 

pDetai1s->pszExecutable  = "TEXT.EXE"; 
pDetail s->pszParameters  = NULL; 
pDetai1s->pszStartupDir  = ""; 
pDetails->pszICON  = "T.ICO"; 

pDetail s->pszEnvironment  = "WORKPLACE\0\0" ; 

pDetails->swpInitial  .fl  = SWP_ACTIVATE;  /*  window  positioning  */ 
p0etails->swplnitial .cy  = 0;  /*  width  of  window  */ 

pDetail s->swplnitial .cx  = 0;  /*  height  of  window  */ 

pDetails->swpInitial .y  = 0;  /*  lower  edge  of  window  */ 

pDetail s->swplnitial.x  = 0;  /*  left  edge  of  window  */ 

pDetail s->swplnitial .hwndlnsertBehind  = HWND_T0P; 

pDetail s->swplnitial .hwnd  = hwndNotify; 

pDetails->swpInitial .ulReservedl  = 0; 

pDetail s->swplnitial .ulReserved2  = 0; 

happ  = WinStartApp(  hwndNotify, pDetails, NULL, NULL, SAF_STARTCHILDAPP) ; 


WinTerminateApp(happ) ; 
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WinStartTimer  - 
Start  Timer 


#define  INCL_WINTIMER  /*  Or  use  INCL_WIN  or  INCL_PM  */ 


ULONG  WinStartTimer  (HAB  hab,  HWND  hwnd,  ULONG  IdTImer,  ULONG  ulTimeout) 


This  function  starts  a timer. 

Parameters 

hab  (HAB)  - input 

Anchor-block  handle. 

hwnd  (HWND)  - input 

Window  handle  that  is  part  of  the  timer  identification. 

NULLHANDLE  The  idTimer  parameter  is  ignored,  and  this  function  returns  a unique,  nonzero, 
identity  which  represents  that  timer.  The  timer  message  is  posted  in  the  queue 
associated  with  the  current  thread,  with  the  hwnd  parameter  of  the  QMSG 
structure  set  to  NULLHANDLE. 

Other  Window  handle. 

IdTimer  (ULONG)  - input 
Timer  identifier. 

The  value  of  an  application-timer  identifier  must  be  below  TID_USERMAX  to  avoid  clashes  with 
timers  used  by  the  system. 

A timer  identification,  TID_SCROLL,  is  created  by  a scroll  bar  control.  An  application  does  not 
normally  see  the  associated  WM_TIMER,  but  passes  it  to  the  scroll-bar  control. 

A timer  identification,  TID_CURSOR,  is  created  when  the  cursor  is  flashing.  An  application  must 
ensure  that  the  associated  WM_TIMER  is  passed  on  to  the  default  window  procedure. 

ulTimeout  (ULONG)  - input 
Delay  time  in  milliseconds. 


Returns 

Return  code. 

When  hwnd  is  set  to  NULLHANDLE: 

0 Error  occurred 

Other  Timer  identity. 

Possible  returns  from  WinGetLastError 

PMERRJNVALID  HWND  An  invalid  window  handle  was  specified. 

Remarks 

This  function  creates  a timer  identified  by  hwnd  and  idTimer,  set  to  time  out  every  ulTimeout 
milliseconds.  When  a timer  times  out,  a WM_TIMER  message  is  posted. 

A ulTimeout  value  of  zero  causes  the  timer  to  timeout  as  fast  as  possible;  generally,  this  is  about 
1/18  second. 

A second  call  to  this  function,  for  a timer  that  already  exists,  resets  that  timer. 
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WinStartTimer 
Start  Timer 


«• 


Related  Functions 

• WinGetCurrentTime 

• WinQueryMsgTime 

• WinStopTimer 

Related  Messages 

• WM_TIMER 


Example  Code 

This  example  uses  the  WinStartTimer  call  to  add  up  elapsed  seconds. 

fdefine  INCL_WINTIMER 
finclude  <0S2.H> 

HAB  hab ; /*  anchor-block  handle.  */ 

ULONG  seconds; 

ULONG  msg; 

WinStartTimer (hab, 

(HWND)O, 

0,  /*  ignored  because  previous  parameter  */ 
/*  is  null . */ 

1000UL); 


switch (msg) 

{ 

case  WM_TIMER: 
seconds  +=  1; 
break; 

} 
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WinStopTimer  - 
Stop  Timer 


#define  INCL_WINTIMER  /*  Or  use  INCL_WIN  or  INCL_PM  */ 


BOOL  WinStopTimer  (HAB  hab,  HWND  hwnd,  ULONG  ulTImer) 


This  function  stops  a timer. 


Parameters 

hab  (HAB)  - input 

Anchor-block  handle. 


hwnd  (HWND)  - input 
Window  handle. 

ulTImer  (ULONG)  - input 
Timer  identifier. 


Returns 

Success  indicator: 

TRUE  Successful  completion 

FALSE  Error  occurred,  or  timer  did  not  exist. 

Possible  returns  from  WinGetLastError 

PMERR  INVALID  HWND  An  invalid  window  handle  was  specified. 

Remarks 

When  this  function  is  called,  no  further  messages  are  received  from  the  stopped  timer,  even  if  it  has 
timed  out  since  the  last  call  to  WinGetMsg. 


Related  Functions 

• WinGetCurrentTime 

• WinQueryMsgTime 

• WinStartTimer 
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WinStopTimer 
Stop  Timer 


Example  Code 

This  example  uses  the  WinStopTimer  call  to  stop  a clock  after  one  minute. 

fdefine  INCL_WINTIMER 
finclude  <0S2.H> 

HAB  hab;  /*  anchor-block  handle.  */ 

ULONG  ulTimerld; 

HWND  hwnd; 

ulTimerld  = WinStartTimer(hab, 

(HWND)O, 

0,  /*  ignored  because  previous  parameter  */ 

/*  is  null . */ 

1000UL); 

BOOL  WndProc(.  . . . ) { 
static  ULONG  seconds; 

switch(msg) 

{ 

case  WM_TIMER: 
if  (seconds)  { 
seconds  ++  ; 

if  (seconds  ==  60)  WinStopTimer(hab,  hwnd,  ulTimerld); 

} 

break; 

case  WM_CREATE: 
seconds  = 0; 


} 
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WinStoreWindowPos  - 
Store  Window  Position 


#define  INCL_WINWORKPLACE 


BOOL  WinStoreWindowPos  (PSZ  pszAppName,  PSZ  pszKeyName,  HWND  hwnd) 


The  WinStoreWindowPos  function  will  save  the  current  size  and  position  of  the  window  specified  by 
hwnd. 

Parameters 

pszAppName  (PSZ)  - input 

A pointer  to  a zero-terminated  string  which  contains  the  application  name. 
pszKeyName  (PSZ)  - input 

A pointer  to  a zero-terminated  string  which  contains  the  key  name, 
hwnd  (HWND)  - input 

Window  handle  for  the  window  to  be  stored. 

Returns 

Success  indicator: 

TRUE  Successful  completion 
FALSE  Error  occurred. 

Remarks 

This  function  will  also  save  the  presentation  parameters. 

Related  Functions 

• WinRestoreWindowPos 
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WinSubclassWindow 
Subclass  Window 


#define  INCL_WINWINDOWMGR  /*  Or  use  INCL_WIN  or  INCL_PM  7 


PFNWP  WinSubclassWindow  (HWND  hwnd,  PFNWP  pNewWindowProc) 


This  function  subclasses  the  indicated  window  by  replacing  its  window  procedure  with  another 
window  procedure,  specified  by  pNewWindowProc. 


Parameters 

hwnd  (HWND)  - input 

Handle  of  window  that  is  being  subclassed. 

pNewWindowProc  (PFNWP)  - input 
New  window  procedure. 

Window  procedure  used  to  subclass  hwnd. 


Returns 

Old  window  procedure. 

Previous  window  procedure  belonging  to  hwnd. 

If  this  function  fails,  OL  is  returned. 

Possible  returns  from  WinGetLastError 

PMERR  INVALID  HWND  An  invalid  window  handle  was  specified. 

Remarks 

To  subclass  a window  effectively,  the  new  window  procedure  calls  the  old  window  procedure  rather 
than  WinDefWindowProc,  for  those  messages  it  does  not  process  itself. 

To  reverse  the  effect  of  subclassing,  call  this  function  again  using  the  old  window  procedure  address. 
Note:  It  is  not  possible  to  subclass  a window  created  by  another  process. 

Related  Functions 

• WinCalcFrameRect 

• WinCreateFrameControls 

• WinCreateStdWindow 

• WinCreateWindow 

• WinDefWindowProc 

• WinDestroyWindow 

• WinQueryClassInfo 

• WinQueryClassName 

• WinRegisterClass 
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WinSubclassWindow  - 
Subclass  Window 


Example  Code 

This  example  uses  the  WinSubclassWindow  call  to  subclass  the  frame  window  procedure,  so  that 
frame-sizing  restrictions  can  be  implemented. 

fdefine  INCL_WINWINDOWMGR 
finclude  <0S2.H> 

HAB  hab; 

PFNWP  FrameWndProc,  OldpFrame; 

HWND  hwndFrame; 


OldpFrame  = WinSubclassWindow(hwndFrame, 

(PFNWP)FrameWndProc) ; 


MRESULT  EXPENTRY  FrameWndProc (hwnd,  msg,  mpl,  mp2) 

{ 


switch (msg)  { 
case  . . . 


default: 

01dpFrame(hwnd,  msg,  mpl,  mp2); 

} 


} 
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WinSubstituteStrings 
Substitute  Strings 


#define  INCL_WINDIALOGS  /*  Or  use  INCL_WIN  or  INCL_PM  */ 


LONG  WinSubstituteStrings  (HWND  hwnd,  PSZ  pszSrc,  LONG  IDestMax,  PSZ  pszDest) 


This  function  performs  a substitution  process  on  a text  string,  replacing  specific  marker  characters 
with  text  supplied  by  the  application. 


Parameters 

hwnd  (HWND)  - input 

Handle  of  window  that  processes  the  call. 

pszSrc  (PSZ)  - input 
Source  string. 

This  is  the  text  string  that  is  to  have  substitution  performed. 

IDestMax  (LONG)  - input 

Maximum  number  of  characters  returnable. 

This  is  the  maximum  number  of  characters  that  can  be  returned  in  pszDest. 

pszDest  (PSZ)  - output 
Resultant  string. 

This  is  the  text  string  produced  by  the  substitution  process. 

The  string  is  truncated  if  it  would  otherwise  contain  more  than  IDestMax  characters.  When 
truncation  occurs,  the  last  character  of  the  truncated  string  is  always  the  null-termination 
character. 

Returns 

Actual  number  of  characters  returned. 

This  is  the  actual  number  returned  in  pszDest,  excluding  the  null-termination  character.  The 
maximum  value  is  (IDestMax— 1).  It  is  zero  if  an  error  occurred. 

Possible  returns  from  WinGetLastError 

PMERRINVALIDHWND  An  invalid  window  handle  was  specified. 

Remarks 

When  a string  of  the  form  “%n”  (where  n is  in  the  range  0 through  9)  occurs  in  the  source  string,  a 
WMSUBSTITUTESTRING  message  is  sent  to  the  specified  window.  This  message  returns  a text 
string  to  use  as  a substitution  for  “%n"  in  the  destination  string,  which  is  otherwise  an  exact  copy  of 
the  source  string. 

If  “%%”  occurs  in  the  source,  “%”  is  copied  to  the  destination,  but  no  other  substitution  occurs.  If 
“%x”  occurs  in  the  source,  where  x is  not  a digit  or  “%,”  the  source  is  copied  unchanged  to  the 
destination.  The  source  and  destination  strings  must  not  overlap  in  memory. 

This  function  is  particularly  useful  for  displaying  variable  information  in  dialogs,  menus,  and  other 
user-interface  calls.  Variable  information  can  include  such  things  as  file  names,  which  cannot  be 
statically  declared  within  resource  files. 

This  function  is  called  by  the  system  while  creating  child  windows  in  a dialog  box.  It  allows  the  child 
windows  to  perform  textual  substitutions  in  their  window  text. 
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WinSubstituteStrings  - 
Substitute  Strings 


Related  Functions 

• WinCompareStrings 

• WinLoadString 

• WinNextChar 

• WinPrevChar 

• Winllpper 

• WinUpperChar 

Related  Messages 

• WMSUBSTITUTESTRING 

Example  Code 

This  example  shows  how  the  substitution  process  works  when  the  WinSubstituteStrings  call  is  made. 

fdefine  INCLJIINDIALOGS 
finclude  <0S2.H> 

static  MRESULT  ClientWindowProc(  HWND  hwnd,  ULONG  msg,  MPARAM  mpl,  MPARAM  mp2  ); 
test() 

{ 

HWND  hwnd; 

char  source[]  = “ this  is  the  source  string:  %1 
char  result[22]; 

MPARAM  mpl; 

ULONG  msg; 

/* 

This  function  performs  a substitution  process  on  a text  string, 
replacing  specific  marker  characters  with  text  supplied  by  the 
appl ication. 

*/ 


Wi nSubsti tuteStri ngs (hwnd , 
source, 

sizeof( source) , 
result); 

/*  WM_SUBSTITUTESTRING  message  is  sent  to  the  window  defined  by  */ 
/*  hwnd.  */ 


} 

static  MRESULT  ClientWindowProc{  HWND  hwnd,  ULONG  msg,  MPARAM  mpl,  MPARAM  mp2  ) 

{ 

switch(msg) 

{ 

case  WM_SUBSTITUTESTRING: 

switch(  (ULONG)mpl) 

{ 

case  1: 

return(MRFROMP("A")); 

break; 

} 

break; 

} 

} 
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WinSubtractRect  - 
Subtract  Rectangle 


#define  INCL_WINRECTANGLES  /*  Or  use  INCL_WIN  or  INCL_PM  */ 


BOOL  WinSubtractRect  (HAB  hab,  PRECTL  prciDest,  PRECTL  prcISrcl,  PRECTL  prclSrc2) 


This  function  subtracts  one  rectangle  from  another. 


Parameters 

hab  (HAB)  - input 

Anchor-block  handle. 

prciDest  (PRECTL)  - output 
Result. 

The  result  of  the  subtraction  of  prclSrc2  from  prcISrcl. 

Note:  The  value  of  each  field  in  this  structure  must  be  in  the  range  —32  768  through  32  767.  The 
data  type  WRECT  may  also  be  used,  if  supported  by  the  language. 

prcISrcl  (PRECTL)  - input 
First  source  rectangle. 

Note:  The  value  of  each  field  in  this  structure  must  be  in  the  range  —32  768  through  32  767.  The 
data  type  WRECT  may  also  be  used,  if  supported  by  the  language. 

prclSrc2  (PRECTL)  - input 
Second  source  rectangle. 

Note:  The  value  of  each  field  in  this  structure  must  be  in  the  range  —32  768  through  32  767.  The 
data  type  WRECT  may  also  be  used,  if  supported  by  the  language. 


Returns 

Not-empty  indicator: 

TRUE  Rectangle  is  not  empty 

FALSE  Rectangle  is  empty  or  an  error  occurred. 

Remarks 

Subtracts  prclSrc2  from  prcISrcl.  prcISrcl,  prclSrc2,  and  prciDest  must  be  distinct  RECTL 
structures. 

Subtracting  one  rectangle  from  another  does  not  always  result  in  a rectangular  area.  When  this 
occurs,  this  function  returns  prcISrcl  in  prciDest.  For  this  reason,  this  function  provides  only  an 
approximation  of  subtraction.  However,  the  area  described  by  prciDest  is  always  greater  than,  or 
equal  to,  the  true  result  of  the  subtraction. 

The  GpiCombineRegion  function  can  be  used  to  calculate  the  true  result  of  the  subtraction  of  two 
rectangular  areas.  The  WinSubtractRect  function  is  much  faster. 
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WinSubtractRect  - 
Subtract  Rectangle 


Related  Functions 

• WinCopyRect 

• WinEqualRect 

• WinFillRect 

• WinlnflateRect 

• WinlntersectRect 

• WinlsRectEmpty 

• WinOffsetRect 

• WinPtlnRect 

• WinSetRect 

• WinSetRectEmpty 

• WinllnionRect 

Example  Code 

This  example  uses  the  WinSubstractRect  call  to  subtract  two  rectangles. 

fdefine  INCL_WINRECTANGLES 
finclude  <0S2.H> 

HAB  hab; 

RECTL  resultrcl;  /*  result.  */ 

RECTL  rclminuend={25,  /*  x coordinate  of  left-hand  edge  of  */ 

/*  rectangle.  */ 

25,  /*  y coordinate  of  bottom  edge  of  */ 

/*  rectangle.  */ 

425,/*  x coordinate  of  right-hand  edge  of  */ 

/*  rectangle.  */ 

425};/*  y coordinate  of  top  edge  of  rectangle.  */ 

RECTL  rclsubtrahend={15,  /*  x coordinate  of  left-hand  edge  of  */ 

/*  rectangle.  */ 

15,  /*  y coordinate  of  bottom  edge  of  */ 

/*  rectangle.  */ 

125,/*  x coordinate  of  right-hand  edge  of  */ 

/*  rectangle.  */ 

125};/*  y coordinate  of  top  edge  of  rectangle.*/ 


Wi nSubtractRect ( hab , 

&resultrcl , 
&rclminuend, 

&rcl subtrahend); 
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#define  INCL_WINSWITCHLIST  /*  Or  use  INCL_WIN  or  INCL_PM  7 


ULONG  WinSwitchToProgram  (HSWITCH  hswItchSwHandle) 


This  function  makes  a specific  program  the  active  program. 


Parameters 

hswItchSwHandle  (HSWITCH)  - input 

Window  List  entry  handle  of  program  to  be  activated. 

Returns 

Return  code. 

0 Successful  completion. 

INV_SWITCH_LIST_ENTRY_HANDLE  Invalid  Window  List  entry  handle  of  the  program  to  be 

activated. 

NOT_PERMITTED_TO_CAUSE_SWITCH  Requesting  program  is  not  the  current  foreground 

process. 


Possible  returns  from  WinGetLastError 

PMERR  INVALID  SWITCH  HANDLE  An  invalid  Window  List  entry  handle  was  specified. 

Remarks 

Use  of  this  function  causes  another  window  (and  its  related  windows)  of  a PM  session  to  appear  on 
the  front  of  the  screen,  or  a switch  to  another  session  in  the  case  of  a non-PM  program.  In  either 
case,  the  keyboard  (and  mouse  for  the  non-PM  case)  input  is  directed  to  the  new  program. 

A program  can  only  be  made  the  foreground  process  by  the  application  which  is  the  current 
foreground  process.  This  function  is  ignored  if  the  issuer  is  not  the  current  foreground  process. 

A foreground  process  is  defined  as  being  any  process  within  the  active  non-PM  session,  or  the 
window  with  the  input  focus  for  a PM  session. 


Related  Functions 

• WinAddSwitchEntry 

• WinChangeSwitchEntry 

• WinCreateSwitchEntry 

• WinQuerySessionTitle 

• WinQuerySwitchEntry 

• WinQuerySwitchHandJe 

• WinQuerySwitchList 

• WinQueryTaskSizePos 

• WinQueryTaskTitle 

• WinRemoveSwitchEntry 
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Example  Code 

This  example  calls  WinSwitchToProgram  to  make  a window  the  foreground  process. 

fdefine  INCL_WINSWITCHLIST 
finclude  <0S2.H> 

HAB  hab; 

HWND  hwndFrame; 

HSWITCH  hswitch; 

hswitch  = WinQuerySwitchHandle(hwndFrame,  0); 

WinSwitchToProgram( hswitch);  /*  will  switch  to  window  defined  */ 

/*  by  hwndFrame.  */ 
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#define  INCL_WINWINDOWMGR  /*  Or  use  INCL_WIN  or  INCL_PM.  Also  in  COMMON  section  7 


BOOL  WinTerminate  (HAB  hab) 


This  function  terminates  an  application  thread's  use  of  the  Presentation  Manager  and  releases  all  of 
its  associated  resources. 

Parameters 

hab  (HAB)  - input 

Anchor-block  handle. 


Returns 

Termination  indicator: 

TRUE  Application  usage  of  Presentation  Manager  successfully  terminated 

FALSE  Application  usage  of  Presentation  Manager  not  successfully  terminated,  or 
Winlnitialize  has  not  been  issued  on  this  thread. 

Remarks 

It  is  good  practice  to  issue  this  function  before  terminating  an  application  thread.  Before  issuing  this 
function,  the  application  must  destroy  all  windows  and  message  queues  that  have  been  created  by 
the  thread,  and  return  any  cached  presentation  spaces  to  the  cache.  If  it  does  not  do  so,  the  results, 
and  the  return  value  from  this  and  subsequent  calls  are  indeterminate. 


Related  Functions 

• WinCancelShutdown 

• WinCreateMsgQueue 

• Winlnitialize 
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Example  Code 

This  example  calls  WinTerminate  in  a typical  termination  sequence. 

fdefine  INCL_WINWINDOWMGR 
finclude  <0S2.H> 

HAB  hab; 

HWND  hwndFrame; 

QMSG  qmsg; 

HMQ  hmq; 

whi1e(  WinGetMsg(  hab,  &qmsg,  NULL,  0,  0 ) ) 


WinDispatchMsg(  hab,  /*  PM  anchor  block  handle  */ 

&qmsg  );  /*  pointer  to  message  */ 

/*  Destroy  the  standard  windows  if  they  were  created.  */ 

if  ( hwndFrame  !=  NULL  ) 

WinDestroyWindow(  hwndFrame  );  /*  frame  window  handle  */ 

/*  Destroy  the  message  queue  and  release  the  anchor  block.  */ 

if  ( hmq  !=  NULL  ) 

WinDestroyMsgQueue(  hmq  ); 

if  ( hab  !=  NULL  ) 

WinTerminate(  hab  ); 
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#define  INCL_WINWINDOWMGR  /*  Or  use  INCL_WIN  or  INCL_PM  */ 


BOOL  WinTerminateApp  (HAPP  happ) 


This  function  terminates  an  application  previously  started  with  the  WinStartApp  function. 

Parameters 

happ  (HAPP)  - input 
Anchor-block  handle. 

Identifies  the  application  to  terminate. 

Returns 

Termination  indicator: 

TRUE  Application  successfully  terminated 
NULL  Error  occurred. 

Possible  returns  from  WinGetLastError 

PMERR_INVALID_HAPP  The  application  handle  passed  to  WinTerminateApp  does 

not  correspond  to  a valid  session. 

PMERR_CANNOT_STOP  The  session  cannot  be  stopped. 

Remarks 

The  application  to  terminate  must  have  been  started  using  the  WinStartApp  function  with  the 
SAF_STARTCHILDAPP  option  specified. 

If  the  specified  application  does  not  stop,  this  function  returns  TRUE.  T o ensure  that  the  application 
has  terminated,  the  application  calling  WinTerminateApp  must  wait  for  the  appropriate  message  to 
be  posted  to  the  window  specified  in  the  WinStartApp  function. 

The  WinTerminateApp  function  must  be  called  from  the  same  process  as  the  WinStartApp  function. 
This  function  requires  the  existence  of  a message  queue. 

Related  Functions 

• WinStartApp 


8-544  PM  Programming  Reference 


WinTerminateApp  - 
Terminate  Application 


Example  Code 

This  example  calls  WinTerminate  in  a typical  termination  sequence. 

fdefine  INC1 _DOSSESMGR 
finclude  <os2.h> 

HWND  hwndNotify; 

PPROGDETAILS  pDetails; 

HAPP  happ; 


pDetails- 
pDetails- 
pDetail  s- 
pDetails- 
pDetails- 
pDetails- 
pDetails- 
pDetails- 
pDetail s- 
pDetails- 
pDetails- 
pDetails- 
pDetail s- 
pDetails- 
pDetails 
pDetails- 
pDetail s- 
pDetail  s- 


•>Length 

■>progt.progc 

■>progt.fbVisible 

•>pszTitle 

>pszExecutable 

>pszParameters 

■>pszStartupDir 

>pszIC0N 

>pszEnvironment 

■>swplnitial .fl 

■>swplnitial  .cy 

•>swplnitial  .cx 

■>swplnitial  .y 

■>swplnitial  .x 


sizeof(PROGDETAILS) ; 
PR0G_WIND0WABLEVI0; 

SHE_VISIBLE; 

"TEXT" ; 

"TEXT.EXE"; 

NULL; 

II  II  . 

"t! ICO" ; 

"WORKPLACE\0\0"; 

SWP_ACTIVATE;  /‘window  positioning  */ 


/*  width  of  window  */ 

/*  height  of  window  */ 

/*  lower  edge  of  window  */ 
/*  left  edge  of  window  */ 


•>swplnitial .hwndlnsertBehind  = HWND_T0P; 

■>swplnitial.hwnd  = hwndNotify; 

>swpInitial.ulReservedl  = 0; 

>swplnitial  .ulReserved2  =0; 


happ  = WinStartApp(  hwndNotify, pDetails, NULL, NULL, SAF_STARTCHILDAPP); 


Wi nT ermi nateApp (happ) ; 
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#define  INCL_WINTRACKRECT  /*  Or  use  INCL_WIN  or  INCL_PM  */ 


BOOL  WinTrackRect  (HWND  hwnd,  HPS  hps,  PTRACKINFO  ptlTracklnfo) 


This  function  draws  a tracking  rectangle. 


Parameters 

hwnd  (HWND)  - input 

Window  handle  where  tracking  is  to  take  place. 

It  is  assumed  that  the  style  of  this  window  is  not  WS_CLIPCHILDREN. 

HWND  DESKTOP  Track  over  the  entire  screen 

Other  Track  over  specified  window  only. 

hps  (HPS)  - input 

Presentation-space  handle. 

Used  for  drawing  the  clipping  rectangle: 

NULLHANDLE  The  hwnd  parameter  is  used  to  calculate  a presentation  space  for  tracking.  It  is 
assumed  that  tracking  takes  place  within  hwnd  and  that  the  style  of  this  window 
is  not  WS_CLIPCHILDREN.  Thus,  when  the  drag  rectangle  appears,  it  is  not 
clipped  by  any  children  within  the  window.  If  the  window  style  is 
WS_CLIPCHILDREN  and  the  application  causes  the  drag  rectangle  to  be 
clipped,  it  must  explicitly  pass  an  appropriate  presentation  space. 

Other  Specified  presentation-space  handle. 

ptlTracklnfo  (PTRACKINFO)  - input/output 

Track  information. 


Returns 

Success  indicator: 

TRUE  Tracking  successful. 

FALSE  Tracking  canceled,  or  the  pointing  device  was  already  captured  when  this  function  was 
called. 

Only  one  tracking  rectangle  can  be  in  use  at  one  time. 

Possible  returns  from  WinGetLastError 

PMERRJNVALID  HWND  An  invalid  window  handle  was  specified. 

Remarks 

The  WinTrackRect  call  provides  general-purpose  pointing-device  tracking.  It  draws  a rectangle  and 
enables  the  user  to  position  the  entire  rectangle,  or  size  a specific  side  or  corner,  as  required.  The 
resulting  rectangle  is  then  returned  to  the  application,  which  can  use  this  new  information  for  size 
and  position  data.  The  window  manager  interface  for  moving  and  sizing  windows  by  means  of  the 
wide  sizing  borders  uses  this  function,  for  example. 

This  function  enables  the  caller  to  control  such  limiting  values  as: 

• A maximum  and  minimum  tracking  size 

• Absolute  tracking-position  limits 

• The  tracking  rectangle  side  widths 

• A restriction  of  tracking  rectangle  movements  to  a predefined  positional  grid. 
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It  automatically  calls  WinLockWindowllpdate  to  prevent  output  in  the  window  hwnd  and  its 
descendants  while  tracking.  When  tracking  has  been  completed,  output  is  enabled  before  this 
function  returns.  It  also  determines  which  button  of  the  pointing  device  is  depressed  at  the  start  of 
the  operation,  and  only  completes  the  tracking  operation  when  the  same  button  is  released. 

If  the  fs  parameter  of  the  TRACKINFO  structure  specified  by  the  TF_SETPOINTERPOS  value  is 
included,  the  pointing  device  pointer  is  positioned  at  the  center  of  the  tracking  rectangle.  Otherwise, 
the  pointing  device  pointer  is  not  moved  from  its  current  position  and  delta  is  established  between 
the  pointing  device  position  and  the  part  of  the  tracking  rectangle  that  it  moves  (the  delta  is  kept 
constant). 


While  moving  or  sizing  with  the  keyboard  interface,  the  pointing  device  pointer  is  repositioned  with 
the  tracking  rectangle’s  new  size  or  position. 


While  tracking,  these  keys  are  active: 

Enter  Accepts  the  new  position  or  size. 

Left  cursor  Moves  the  pointing  device  pointer  and  tracking  rectangle  left. 

If  the  pointing  device  pointer  is  on  the  upper  or  lower  edge  of  the  tracking  rectangle, 
the  pointer  is  moved  to  the  top-left  or  bottom-left  corner  respectively. 

Up  cursor  Moves  the  pointing  device  pointer  and  tracking  rectangle  up. 

If  the  pointing  device  pointer  is  on  the  left  or  right  edge  of  the  tracking  rectangle,  the 
pointer  is  moved  to  the  top-left  or  top-right  corner  respectively. 

Right  cursor  Moves  the  pointing  device  pointer  and  tracking  rectangle  right. 

If  the  pointing  device  pointer  is  on  the  upper  or  lower  edge  of  the  tracking  rectangle, 
the  pointer  is  moved  to  the  top-right  or  bottom-right  corner  respectively. 

Down  cursor  Moves  the  pointing  device  pointer  and  tracking  rectangle  down. 

If  the  pointing  device  pointer  is  on  the  left  or  right  edge  of  the  tracking  rectangle,  the 
pointer  is  moved  to  the  bottom-left  or  bottom-right  corner  respectively. 


Esc 


Cancels  the  current  tracking  operation.  The  value  of  the  tracking  rectangle  is 
undefined  on  exit. 


The  pointing  device  and  the  keyboard  interface  can  be  intermixed.  The  caller  need  not  include  the 
TF_SETPOINTERPOS  value  to  use  the  keyboard  interface,  as  this  value  simply  initializes  the  position 
of  the  pointing  device  pointer. 

If  TF_GRID  is  specified  in  the  TRACKINFO  structure,  the  interior  of  the  tracking  rectangle  is  restricted 
to  multiples  of  the  values  of  the  cxGrid  and  cyGrid  parameters.  The  default  values  for  these  are  the 
system  font  character  width  and  half  the  system  font  character  height,  respectively. 

Tracking  movements  using  the  keyboard  arrow  keys  depend  on  whether  or  not  TF_GRID  is  specified 
in  the  TRACKINFO  structure,  If  not  specified,  the  increments  are  the  values  of  cxKeyboard  and 
cyKeyboard.  If  specified  the  increments  are  the  largest  multiples  of  cxGrid  and  cyGrid  that  do  not 
exceed  cxKeyboard  and  cyKeyboard,  respectively.  If  cxGrid  exceeds  cxKeyboard,  or  cyGrid 
exceeds  cyKeyboard,  the  keyboard  arrow  keys  do  not  cause  tracking. 

The  tracking  rectangle  is  usually  logically  “on  top”  of  objects  it  tracks,  so  that  the  user  can  see  the 
old  size  and  position  while  tracking  the  new.  Thus,  it  is  possible  for  a window  “below”  the  tracking 
rectangle  to  be  updated  while  part  of  the  tracking  rectangle  is  “above”  it. 

Because  the  tracking  rectangle  is  drawn  in  exclusive-OR  mode,  no  window  can  draw  below  the 
tracking  rectangle  (and  thereby  obliterate  it)  without  first  notifying  the  tracking  code,  because 
unwanted  areas  of  the  tracking  rectangle  can  be  left  behind.  If  the  window  doing  the  drawing  is 
clipped  out  from  the  window  in  which  the  tracking  is  occurring,  this  problem  does  not  arise. 
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To  prevent  a window  that  is  currently  processing  a WMPAINT  message  drawing  over  the  tracking 
rectangle,  the  tracking  rectangle  is  considered  as  a system-wide  resource,  only  one  of  which  can  be 
in  use  at  any  time.  If  there  is  a risk  of  the  currently-updating  window  drawing  on  the  tracking 
rectangle,  the  tracking  rectangle  is  removed  while  that  window  and  its  child  windows  update,  and  it 
is  then  replaced.  This  is  done  during  the  WinBeginPaint  and  WinEndPaint  functions.  If  the  tracking 
rectangle  overlaps,  it  is  removed  in  the  WinBeginPaint  function.  In  the  WinEndPaint  function,  all  the 
child  windows  are  updated  by  means  of  the  WinllpdateWindow  function  before  the  tracking  rectangle 
is  redrawn. 

WinTrackRect  has  a modal  loop  within  it.  The  loop  has  a HK_MSGFILTER  hook  and  a MSGF_TRACK 
hook  code. 

Note:  The  rectangle  tracked  by  this  function  stays  within  the  specified  tracking  bounds  and 

dimensions.  If  the  rectangle  passed  is  out  of  these  bounds,  or  it  is  too  large  or  too  small,  it  is 
modified  to  a rectangle  that  meets  these  limits. 


Related  Functions 

• WinShowTrackRect 

Related  Messages 

• WM_PAINT 
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Example  Code 

This  example  shows  how  WinTrackRect  can  be  used  to  allow  a user  size  a rectangle  on  the  screen. 
Idefine  INCL_WINTRACKRECT 

finclude  <os2.h> 

BOOL  MyTrackRoutine(HAB  hab,  HPS  hps,  PRECTL  rcl) 

{ 

TRACKINFO  track; 
track. cxBorder  = 4; 

track. cyBorder  =4;  /*  4 pel  wide  lines  used  for  rectangle  */ 
track.cxGrid  = 1; 

track. cyGrid  = 1;  /*  smooth  tracking  with  mouse  */ 

track.cxKey board  = 8; 

track. cyKey board  = 8;  /*  faster  tracking  using  cursor  keys  */ 

WinCopyRect(hab,  &track. rcl Track,  rcl);  /*  starting  point  */ 

WinSetRect(hab,  &track. rcl Boundary,  0,  0,  640,  480);  /*  bounding  rectangle  */ 
track. ptlMinTrackSize.x  = 10; 

track. ptlMinTrackSize.y  = 10;  /*  set  smallest  allowed  size  of  rectangle  */ 
track. ptlMaxTrackSize.x  = 200; 

track. ptlMaxTrackSize.y  = 200;  /*  set  largest  allowed  size  of  rectangle  */ 
track. fs  = TF_M0VE ; 

if  (WinTrackRect (HWND_DESKTOP,  hps,  fctrack)  ) 

{ 

/*  if  successful  copy  final  position  back  */ 

WinCopyRect(hab,  rcl,  &track.rclTrack) ; 
return (TRUE); 

} 

else 

{ 

return (FALSE) ; 

} 

} 
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#define  INCL_WINACCELERATORS  /*  Or  use  INCL_WIN  or  INCL_PM  */ 


BOOL  WlnT ranslateAccel  (HAB  hab,  HWND  hwnd,  HACCEL  hacceiAccel,  PQMSG  pQmsg) 


This  function  translates  a WMCHAR  message. 


Parameters 

hab  (HAB)  - input 

Anchor-block  handle. 

hwnd  (HWND)  - input 
Destination  window. 

hacceiAccel  (HACCEL)  - input 
Accelerator-table  handle. 

pQmsg  (PQMSG)  - input/output 
Message  to  be  translated. 


Returns 

Success  indicator: 

TRUE  Successful  completion 
FALSE  Error  occurred. 

Possible  returns  from  WinGetLastError 

PMERR  INVALID  HWND  An  invalid  window  handle  was  specified. 

PMERR_INVALID_HACCEL  An  invalid  accelerator-table  handle  was  specified. 

Remarks 

This  function  translates  pQmsg  if  it  is  a WM_CHAR  message  in  the  accelerator  table  hacceiAccel. 

The  message  is  translated  into  a WM_COMMAND,  WMSYSCOMMAND,  or  WM  HELP  message,  with 
hwnd  identifying  the  destination  window.  Normally,  this  parameter  is  a frame-window  handle.  This 
function  does  not  highlight  menu  items. 

If  hacceiAccel  equals  NULL,  the  current  accelerator  table  is  assumed. 

WinTranslateAccel  returns  TRUE  if  the  message  matches  an  accelerator  in  the  table.  pQmsg  is 
modified  by  WinTranslateAccel  if  a match  is  found. 

If  a menu  item  exists  that  matches  the  accelerator-command  value,  and  that  item  is  disabled,  pQmsg 
is  translated  to  a WM_NULL  message,  rather  than  a WM  COMMAND,  WM  SYSCOMMAND,  or 
WM_HELP  message.  If  the  command  is  WM_SYSCOMMAND  or  WM_HELP  (and  if  a 
WM_SYSCOMMAND  or  FID_SYSMENU  child  window  is  searched)  the  menu  child  window  of  hwnd  that 
has  the  FID_MENU  identifier  is  searched. 

It  is  possible  to  have  accelerators  that  do  not  correspond  to  items  in  a menu.  If  the  command  value 
does  not  match  any  items  in  the  menu,  the  message  is  still  translated. 

Generally,  applications  do  not  have  to  call  this  function;  it  is  usually  called  automatically  by 
WinGetMsg  and  WinPeekMsg,  when  a WM_CHAR  message  is  received  with  the  window  handle  of  the 
active  window  as  the  first  parameter.  The  standard  frame  window  procedure  always  passes 
WM_COMMAND  messages  to  the  FID_CLIENT  window.  Because  the  message  is  physically  changed 


8-550  PM  Programming  Reference 


WinTranslate Accel  - 
Translate  Accelerator 


by  WinTranslateAccel,  applications  do  not  see  the  WMCHAR  messages  that  result  in 
WM_COMMAND,  WM_SYSCOMMAND,  or  WM_HELP  messages. 


Related  Functions 

• WinCopyAccelTable 

• WinCreateAccelTable 

• WinDestroyAccelTable 

• WinLoadAccelTable 

• WinQueryAccelTable 

• WinSetAccelTable 

Related  Messages 

• WM_CHAR 

• WM_COMMAND 

• WM_HELP 

• WM_NULL 

• WM_SYSCOMMAND 

Example  Code 

This  example  uses  the  WinTranslateAccel  API  to  translate  WM  CHAR  messages  destined  for  the 
frame  window. 

fdefine  INCL_WINWINDOWMGR 
fdefine  INCL_WINACCELERATORS 
finclude  <0S2.H> 

HACCEL  haccel ; 

HWND  hwndFrame,  hwndClient;  /*  window  handles.  */ 

HAB  hab;  /*  anchor  block.  */ 

QMSG  qmsg; 

hwndFrame  = WinQueryWindow(hwndCl ient, 

QW_PARENT);  /*  get  handle  of  parent,  */ 

/*  which  is  frame  window.  */ 


/*  Now  get  the  accel  table  for  the  frame  window  */ 
haccel  = WinQueryAccelTable(hab, 

hwndFrame) ; 


WinTranslateAccel (hab, 

hwndFrame, 
haccel , 
&qmsg) ; 


swi tch(qmsg.msg) 

{ 

case  WM_COMMAND : 

case  WM_SYSCOMMAND: 

case  WM_HELP: 
break; 
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#define  INCL_WINRECTANGLES  /*  Or  use  INCL_WIN  or  INCL_PM  */ 


BOOL  WinUnionRect  (HAB  hab,  PRECTL  prclDest,  PRECTL  prcISrcl,  PRECTL  prclSrc2) 


This  function  calculates  a rectangle  that  bounds  the  two  source  rectangles. 


Parameters 

hab  (HAB)  - input 

Anchor-block  handle. 

prclDest  (PRECTL)  - output 
Bounding  rectangle. 

Note:  The  value  of  each  field  in  this  structure  must  be  in  the  range  —32  768  through  32  767.  The 
data  type  WRECT  may  also  be  used,  if  supported  by  the  language. 

prcISrcl  (PRECTL)  - input 
First  source  rectangle. 

Note:  The  value  of  each  field  in  this  structure  must  be  in  the  range  —32  768  through  32  767.  The 
data  type  WRECT  may  also  be  used,  if  supported  by  the  language. 

prclSrc2  (PRECTL)  - input 
Second  source  rectangle. 

Note:  The  value  of  each  field  in  this  structure  must  be  in  the  range  —32  768  through  32  767.  The 
data  type  WRECT  may  also  be  used,  if  supported  by  the  language. 


Returns 

Nonempty  indicator: 

TRUE  prclDest  is  a nonempty  rectangle 
FALSE  Error,  or  prclDest  is  an  empty  rectangle. 

Remarks 

prcISrcl  and  prclSrc2  must  not  be  NULL  pointers,  although  the  rectangfes  they  point  to  can  be  empty 
(see  the  WinlsRectEmpty  function). 

If  one  of  the  source  rectangles  is  empty,  the  other  is  returned. 


Related  Functions 

• WinCopyRect 

• WinEqualRect 

• WinFillRect 

• WinlnflateRect 

• WinlntersectRect 

• WinlsRectEmpty 

• WinOffsetRect 

• WinPtlnRect 

• WinSetRect 

• WinSetRectEmpty 

• WinSubtractRect 
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Union  Rectangle 


Example  Code 

This  example  uses  the  WinUnionRect  call  to  find  a rectangle  that  bounds  two  source  rectangles. 


Idefine  INCL_WINRECTANGLES 


linclude  <0S2.H> 
HAB  hab; 

RECTL  resultrcl; 
RECTL  rcla={25, 

25, 

125, 

125}; 

*/ 


/*  result.  */ 

/*  x coordinate  of  left-hand  edge  of  */ 
/*  rectangle.  */ 

/*  y coordinate  of  bottom  edge  of  */ 
/*  rectangle.  */ 

/*  x coordinate  of  right-hand  edge  of  */ 
/*  rectangle.  */ 

/*  y coordinate  of  top  edge  of  rectangle. 


RECTL  rclb  = {15,  /*  x coordinate  of  left-hand  edge  of  */ 
/*  rectangle.  */ 

15,  /*  y coordinate  of  bottom  edge  of  */ 
/*  rectangle.  */ 

125,  /*  x coordinate  of  right-hand  edge  of  */ 
/*  rectangle.  */ 

125}; 


WinUnionRect(hab, 

&resultrcl , 
&rcla, 
&rclb) ; 
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Win  Update  Wi  ndo  w 
Update  Window 


#define  INCL_WINWINDOWMGR  /*  Or  use  INCL_WIN  or  INCL_PM  */ 


BOOL  WlnUpdateWindow  (HWND  hwnd) 


This  function  forces  the  update  of  a window  and  its  associated  child  windows. 

Parameters 

hwnd  (HWND)  - input 
Window  handle. 


Returns 

Window-updated  indicator: 

TRUE  Window  successfully  updated 
FALSE  Window  not  successfully  updated. 

Possible  returns  from  WinGetLastError 

PMERR  INVALID  HWND  An  invalid  window  handle  was  specified. 

Remarks 

If  hwnd  is  an  asynchronous  window,  only  it  and  its  asynchronous  children  are  updated.  They  are 
sent  WMPAINT  messages  from  this  function. 

If  hwnd  is  a synchronous  window,  only  it  and  its  synchronous  children  are  updated.  They  are  sent 
WM_PAINT  messages  from  this  function.  If  the  window  is  owned  by  a different  thread  from  the  thread 
issuing  the  call,  the  message  is  sent  asynchronously  and  not  synchronously. 

If  hwnd  is  a child  of  a nonclip-children  parent,  the  update  region  of  hwnd  is  subtracted  from  the 
update  region  of  the  parent,  if  the  parent  has  one.  This  is  so  that  any  parent-window  drawing  after 
hwnd  does  not  draw  over  whatever  is  drawn  by  hwnd. 


Related  Functions 

• WinBeginPaint 

• WinEnableWindowllpdate 

• WinEndPaint 

• WinExcludellpdateRegion 

• WinGetClipPS 

• WinGetPS 

• WinGetScreenPS 

• WinlnvalidateRect 

• WinlnvalidateRegion 

• WinlsWindowShowing 

• WinlsWindowVisible 

• WinLockVisRegions 

• WinOpenWindowDC 

• WinQueryllpdateRect 

• WinQueryUpdateRegion 

• WinRealizePalette 

• WinReleasePS 

• WinShowWindow 

• WinValidateRect 

• WinValidateRegion 
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WinUpdateWindow  - 
Update  Window 


Related  Messages 

• WM  PAINT 


Example  Code 

This  example  uses  the  WinUpdateWindow  call  to  send  a WM_PAINT  message  to  a window  procedure. 

Idefine  INCLJIINWINDOWMGR 
linclude  <0S2.H> 

Idefine  WMJJSERDEF  WM_USER  + 1 
main() 

{ 

} 

static  MRESULT  ClientWindowProc(  HWND  hwnd,  USHORT  msg,  MPARAM  mpl,  MPARAM  mp2  ) 

{ 

switch (msg) 

{ 

case  WM_PAINT : 
break; 

case  WMJJSERDEF: 

Wi nUpdateWi ndow ( hwnd ) ; 

} 

} 
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WinUpper  - 
Uppercase  String 


#define  INCL_WINCOUNTRY  /*  Or  use  INCL_WIN  or  INCL_PM  */ 


ULONG  WinUpper  (HAB  hab,  ULONG  ulCodepage,  ULONG  ulCountry,  PSZ  pszStrlng) 


This  function  converts  a string  to  uppercase. 

Parameters 

hab  (HAB)  - input 

Anchor-block  handle. 

ulCodepage  (ULONG)  - input 
Code  page: 

0 Use  the  current-process  code  page 

Other  Use  the  specified  code  page. 

ulCountry  (ULONG)  - input 
Country  code: 

0 Use  the  default  country  code  specified  in  CONFIG.SYS 

Other  Use  the  specified  country  code. 

pszStrlng  (PSZ)  - input/output 

String  to  be  converted  to  uppercase. 


Returns 

Length  of  converted  string. 

Possible  returns  from  WinGetLastError 

PMERR  INVALID  STRING  PARM  The  specified  string  parameter  is  invalid. 

Related  Functions 

• WinCompareStrings 

• WinLoadString 

• WinNextChar 

• WinPrevChar 

• WinSubstituteStrings 

• WinUpperChar 
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WinUpper  - 
Uppercase  String 


Example  Code 

This  example  shows  how  the  WinUpper  call  can  be  used  to  convert  a strings  in  NLS  languages  to 
uppercase. 

Idefine  INCLJIINCOUNTRY 
linclude  <0S2.H> 
linclude  <stdio.h> 
main() 

{ 

HAB  hab; 

char  szString[]  = "ihablas  espanol?"; 
hab  = Winlnitial ize(0) ; 

WinUpper(hab, 

850, 

34, 

szString) ; 

WinTerminate(hab) ; 

} 
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WinUpperChar  - 
Uppercase  Character 


#define  INCL_WINCOUNTRY  /*  Or  use  INCL_WIN  or  INCL_PM  7 


ULONG  WinUpperChar  (HAB  hab,  ULONG  ulCodepage,  ULONG  ulCounlry,  ULONG  ullnchar) 


This  function  translates  a character  to  uppercase. 


Parameters 

hab  (HAB)  - input 

Anchor-block  handle. 

ulCodepage  (ULONG)  - input 
Code  page: 

0 Use  the  current-process  code  page 

Other  Use  the  specified  code  page. 

ulCounlry  (ULONG)  - input 
Country  code: 

0 Use  the  default  country  code  specified  i n CONFIG.SYS 

Other  Use  the  specified  country  code. 

ullnchar  (ULONG)  - input 

Character  to  be  translated  to  uppercase. 


Returns 

Translated  character: 

0 Error  occurred 

Other  The  translated  character. 

Possible  returns  from  WinGetLastError 

PMERRINVALIDSTRINGPARM  The  specified  string  parameter  is  invalid. 

Remarks 

The  case-mapping  used  is  the  same  as  provided  by  the  OS/2  DosCaseMap  call. 


Related  Functions 

• WinCompareStrings 

• WinLoadString 

• WinNextChar 

• WinPrevChar 

• WinSubstituteStrings 

• WinUpper 
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WinUpperChar  - 
Uppercase  Character 


Example  Code 

This  example  shows  how  the  WinUpperChar  call  can  be  used  to  convert  a characters  in  NLS 
languages  to  uppercase. 

Idefine  INCL_WINCOUNTRY 
linclude  <0S2.H> 
linclude  <stdio.h> 
main() 

{ 

HAB  hab; 

char  szString[]  = "E"; 
hab  = Winlnitialize(O); 

WinUpper(hab, 

850, 

49, 

szString) ; 

WinTernti  nate(hab) ; 

} 
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WinValidateRect  - 
Validate  Rectangle 


#define  INCL_WINWINDOWMGR  /*  Or  use  INCL_WIN  or  INCL_PM  */ 


BOOL  WinValidateRect  (HWND  hwnd,  PRECTL  prcIRect,  BOOL  flncludeClippedChlldren) 


This  function  subtracts  a rectangle  from  the  update  region  of  an  asynchronous  paint  window, 
marking  that  part  of  the  window  as  visually  valid. 


Parameters 

hwnd  (HWND)  - input 

Handle  of  window  whose  update  region  is  changed. 

If  this  parameter  is  HWND_DESKTOP  or  a desktop-window  handle,  the  function  applies  to  the 
whole  screen  (or  desktop). 

prcIRect  (PRECTL)  - input 

Rectangle  to  be  subtracted  from  the  window's  update  region. 

Note:  The  value  of  each  field  in  this  structure  must  be  in  the  range  —32  768  through  32  767.  The 
data  type  WRECT  may  also  be  used,  if  supported  by  the  language. 

flncludeClippedChlldren  (BOOL)  - input 
Validation-scope  indicator: 

TRUE  Include  descendants  of  hwnd  in  the  valid  rectangle 

FALSE  Include  descendants  of  hwnd  in  the  valid  rectangle,  only  if  parent  is  not 
WS_CLIPCHILDREN. 

Returns 

Success  indicator: 

TRUE  Successful  completion 
FALSE  Error  occurred. 

Possible  returns  from  WinGetLastError 

PMERR  INVALID  HWND  An  invalid  window  handle  was  specified. 

PMERR_INVALID_FLAG  An  invalid  bit  was  set  for  a parameter.  Use  constants 

defined  by  PM  for  options,  and  do  not  set  any  reserved 
bits. 


Remarks 

The  call  is  not  used  for  CS_SYNCPAINT  windows. 

This  function  has  no  effect  on  the  window  if  any  part  of  the  window  has  been  made  invalid  since  the 
last  call  to  WinBeginPaint,  WinQueryUpdateRect,  or  WinQueryUpdateRegion. 


Related  Functions 

• WinBeginPaint 

• WinEnableWindowUpdate 

• WinEndPaint 

• WinExcludeUpdateRegion 

• WinGetClipPS 

• WinGetPS 

• WinGetScreenPS 

• WinlnvalidateRect 
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Wi  n Valid  ate  Rect  - 
Validate  Rectangle 


• WinlnvalidateRegion 

• WinlsWindowShowing 

• WinlsWindowVisible 

• WinLockVisRegions 

• WinOpenWindowDC 

• WinQueryllpdateRect 

• WinQueryllpdateRegion 

• WinRealizePalette 

• WinReleasePS 

• WinShowWindow 

• WinUpdateWindow 

• WinValidateRegion 


Example  Code 

The  window  needs  painting.  This  is  done  asynchronously  on  the  drawing  thread.  The  window  update 
region  is  copied  into  a local  region  and  passed  to  the  drawing  thread.  The  window  must  be  validated 
now  (to  prevent  further  unnecessary  paint  messages). 

Idefine  INCLJIINWINDOWMGR 
linclude  <0S2.H> 

HRGN  hrgnUpdate.; 

HPS  hps; 

HWND  hwnd; 

/*  Window  needs  paint  */ 

case  WM_PAINT : 

/*  assume  we  stop  any  asynchronous  drawing.  */ 

/*  by  posting  a message  to  the  asynchronous  */ 

/*  drawing  thread.  */ 

hrgnUpdate=(HRGN)GpiCreateRegion(hps,  /*  Create  empty  region  */ 

GL, 

(PRECTL)NULL) ; 


Wi nQue  ry UpdateRegi on ( hwnd , 

hrgnUpdate) ; 

Wi nVal i dateRect ( hwnd , 

(PRECTL)NULL, 

TRUE) ; 


/*  Save  the  window  update  */ 
/*  region.  */ 

/*  Validate  window  now  to  */ 
/*  stop  more  paint  msgs  */ 


/*  assume  a message  is  posted  to  the  drawing  thread,  passing  */ 

/*  the  update  region:  (MPARAM)hgrnUpdate.  */ 

mr  = (MRESULT)  0L;  /*  Message  processed  */ 

break;  /*  End  window  painting  */ 
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WinValidateRegion 
Validate  Region 


#define  INCL_WINWINDOWMGR  /*  Or  use  INCL_WIN  or  INCL_PM  */ 


BOOL  WinValidateRegion  (HWND  hwnd,  HRGN  hrgn,  BOOL  flncludeCUppedChlldren) 


This  function  subtracts  a region  from  the  update  region  of  an  asynchronous  paint  window,  marking 
that  part  of  the  window  as  visually  valid. 


Parameters 

hwnd  (HWND)  - input 

Handle  of  window  whose  update  region  is  changed. 

If  this  parameter  is  HWND_DESKTOP  or  a desktop  window  handle,  the  function  applies  to  the 
whole  screen  (or  desktop). 

hrgn  (HRGN)  - input 

Handle  of  subtracted  region. 

This  is  the  region  that  is  subtracted  from  the  window’s  update  region. 

flncludeCUppedChlldren  (BOOL)  - input 
Validation-scope  indicator: 

TRUE  Include  descendants  of  hwnd  in  the  valid  region 

FALSE  Include  descendants  of  hwnd  in  the  valid  region,  only  if  parent  is  not 
WS_CLIPCHILDREN. 

Returns 

Success  indicator: 

TRUE  Successful  completion 
FALSE  Error  occurred. 

Possible  returns  from  WinGetLastError 

PMERR  INVALID  HWND  An  invalid  window  handle  was  specified. 

PMERR_HRGN_BUSY  An  internal  region  busy  error  was  detected.  The  region 

was  locked  by  one  thread  during  an  attempt  to  access  it 
from  another  thread. 

PMERR_INVALID_FLAG  An  invalid  bit  was  set  for  a parameter.  Use  constants 

defined  by  PM  for  options,  and  do  not  set  any  reserved 
bits. 


Remarks 

The  call  is  not  used  for  CS_SYNCPAINT  windows. 

The  call  has  no  effect  on  the  window  if  any  part  of  the  window  has  been  made  invalid  since  the  last 
call  to  WinBeginPaint,  WinQueryUpdateRect,  or  WinQueryUpdateRegion. 
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WinValidateRegion  - 
Validate  Region 


Related  Functions 

• WinBeginPaint 

• WinEnableWindowllpdate 

• WinEndPaint 

• WinExcludellpdateRegion 

• WinGetClipPS 

• WinGetPS 

• WinGetScreenPS 

• WinlnvalidateRect 

• WinlnvalidateRegion 

• WinlsWindowShowing 

• WinlsWindowVisible 

• WinLockVisRegions 

• WinOpenWindowDC 

• WinQueryllpdateRect 

• WinQueryUpdateRegion 

• WinRealizePalette 

• WinReleasePS 

• WinShowWindow 

• WinUpdateWindow 

• WinValidateRect 
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WinValidateRegion  - 
Validate  Region 

Example  Code 

This  example  shows  how  an  application  can  incrementally  repaint  an  asynchronous-paint  window 
one  area  at  a time.  While  a window  is  invalid  (has  a non-null  update  region),  WMPAINT  messages 
are  returned  by  WinGetMsg.  The  application  uses  WinQueryllpdateRegion  to  obtain  a region  that 
requires  repainting,  and  WinValidateRegion  to  validate  the  region  (reset  the  update  region  to  null). 

Idefine  INCLJIINWINDOWMGR 
Idefine  INCL_GPIREGIONS 
# include  <0S2.H> 

HRGN  hrgnUpdt,  sRgnType; 

HPS  hpsPaint; 

HWND  hwnd; 

/*  Window  needs  paint  */ 

case  WM_PAINT : 

/*  assume  we  stop  any  asynchronous  drawing.  */ 

/*  by  posting  a message  to  the  asynchronous  */ 

/*  drawing  thread.  */ 

hrgnUpdt  = (HRGN)GpiCreateRegion(hpsPaint, 

(ULONG)O, 

(PRECTL)NULL); 

sRgnType  = (HRGN)WinQueryUpdateRegion(hwnd, 

hrgnUpdt) ; 

/*  if  the  region  is  not  null  and  the  call  is  not  in  error,  */ 

/*  validate  the  region.  */ 

if  ((sRgnType  !=  NULL)  && 

(sRgnType  !=  RGN_ERR0R))  { 

WinValidateRegion (hwnd,  hrgnUpdt,  FALSE); 

/* 

here  we  would  send  the  update  region  handle  to  an 
asynchronous  drawing  thread.  We  have  already  validated  the 
region,  so  no  more  WM_PAINT  messages  will  be  sent  due  to  this 
region. 

*/ 

} else  { GpiDestroyRegi on (hpsPaint,  hrgnUpdt);} 
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WinWaitEventSem  - 
Wait  Event  Semaphore 


#define  INCL_WINMESSAGEMGR 


ULONG  WinWaitEventSem  (HEV  hev,  ULONG  ulTImeout) 


WinWaitEventSem  waits  for  an  event  semaphore  to  be  posted  or  for  a Presentation  Manager 
message. 

Parameters 

hev  (HEV)  - input 

The  handle  of  the  event  semaphore  to  wait  for. 
ulTImeout  (ULONG)  - input 

The  time-out  in  milliseconds.  This  is  the  maximum  amount  of  time  the  user  wants  to  allow  the 
thread  to  be  blocked. 

This  parameter  can  also  have  the  following  values: 

Value  Definition 

0 (SEM_IMMEDIATE_RETURN)  WinWaitEventSem  returns  without  blocking  the  calling 

thread. 

—1  (SEM_INDEFINITE_WAIT)  WinWaitEventSem  blocks  the  calling  thread  indefinitely. 

Returns 

Return  Code. 

WinWaitEventSem  returns  the  following  values: 

0 NO_ERROR 

6 ERROR_INVALID_HANDLE 

8 ERROR_NOT_ENOUGH_MEMORY 

95  ERRORJNTERRUPT 

640  ERROR_TIMEOUT 

Remarks 

WinWaitEventSem  is  similar  to  DosWaitEventSem  and  enables  a thread  to  wait  for  an  event 
semaphore  to  be  posted  or  for  a window  message  sent  by  the  WinSendMsg  function  from  another 
thread  to  be  received. 

This  function  can  be  called  by  any  thread  in  the  process  that  created  the  semaphore.  Threads  in 
other  processes  can  also  call  this  function,  but  they  must  first  gain  access  to  the  semaphore  by 
calling  DosOpenEventSem. 

Since  the  processing  of  a window  message  may  take  longer  than  the  value  specified  by  the  Timeout 
parameter,  this  function  may  not  return  within  the  time  specified  by  that  value. 


Related  Functions 

• WinSendMsg 

• WinPostMsg 
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WinWaitEventSem  - 
Wait  Event  Semaphore 


Example  Code 

This  example  causes  the  calling  thread  to  wait  until  the  specified  event  semaphore  is  posted. 
Assume  that  the  handle  of  the  semaphore  has  been  placed  into  hev  already. 

ulTimeout  is  the  number  of  milliseconds  that  the  calling  thread  will  wait  for  the  event  semaphore  to 
be  posted.  If  the  specified  event  semaphore  is  not  posted  during  this  time  interval,  the  request  times 
out. 

Idefine  INCL_DOSSEMAPHORES  /*  Semaphore  values  */ 

Idefine  INCL_WINMESSAGEMGR 
linclude  <os2.h> 
linclude  <stdio.h> 

lifndef  ERROR JTMEOUT 

Idefine  ERROR  JTMEOUT  640 
Idefine  ERRORJNTERRUPT  95 
lend if 

HEV  hev;  /*  Event  semaphore  handle  */ 

ULONG  ulTimeout;  /*  Number  of  milliseconds  to  wait  */ 

ULONG  rc;  /*  Return  code  */ 

ulTimeout  = 60000;  /*  Wait  for  a maximum  of  1 minute  */ 

rc  = WinWaitEventSem(hev,  ulTimeout); 

if  (rc  ==  ERR0RJIME0UT) 

{ 

printf( "WinWaitEventSem  call  timed  out"); 
return; 

} 

if  (rc  ==  ERRORJNTERRUPT) 

{ 

printf( "WinWaitEventSem  call  was  interrupted"); 
return; 

} 

if  (rc  !=  0) 

{ 

printf( "WinWaitEventSem  error:  return  code  = %ld",  rc); 
return; 

} 
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WinWaitMsg  - 
Wait  Message 


#define  INCL_WINMESSAGEMGR  /*  Or  use  INCL_WIN  or  INCL_PM  */ 


BOOL  WinWaitMsg  (HAB  hab,  ULONG  ulFIrst,  ULONG  ulLast) 


This  function  waits  for  a filtered  message. 

Parameters 

hab  (HAB)  - input 

Anchor-block  handle. 

ulFIrst  (ULONG)  - input 
First  message  identity. 

ulLast  (ULONG)  - input 
Last  message  identity. 


Returns 

Success  indicator: 

TRUE  Successful  completion 
FALSE  Error  occurred. 

Remarks 

This  function  causes  the  current  thread  to  wait  for  a message  to  arrive  on  the  message  queue 
associated  with  hab.  This  must  be  the  next  message  since  the  queue  was  last  inspected  by  a 
fSuccess  return  from  WinGetMsg  or  WinPeekMsg.  It  must  also  conform  to  the  filtering  criteria 
specified  by  ulFirst  and  ulLast. 

For  details  of  the  filtering  performed  by  ulFirst  and  ulLast,  see  the  WinGetMsg  function. 


Related  Functions 

• WinBroadcastMsg 

• WinCreateMsgQueue 

• WinDestroyMsgQueue 

• WinDispatchMsg 

• WinGetDIgMsg 

• WinGetMsg 

• WinlnSendMsg 

• WinPeekMsg 

• WinPostMsg 

• WinPostQueueMsg 

• WinQueryMsgPos 

• WinQueryMsgTime 

• WinQueryQueuelnfo 

• WinQueryQueueStatus 

• WinRegisterUserDatatype 

• WinRegisterUserMsg 

• WinSendDIgltemMsg 

• WinSendMsg 

• WinSetClassMsglnterest 

• WinSetMsglnterest 

• WinSetMsgMode 

• WinSetSynchroMode 
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WinWaitMsg 
Wait  Message 


Example  Code 

In  this  example  the  pointer  is  kept  hidden  until  mouse  activity  is  detected.  The  WinWaitMsg  call  is 
used  to  wait  for  any  mouse  message. 

fdefine  INCL_WINWINDOWMGR 
fdefine  INCLJIINPOINTERS 
fdefine  INCL_WINDESKTOP 
fdefine  INCL_WININPUT 
finclude  <0S2.H> 

HWND  hwnd; 

HPOINTER  hpointer; 

HAB  hab; 

hpointer  = WinQueryPointer(HWND_DESKTOP) ; /*  get  the  pointer  */ 

/*  handle.  */ 

/*  hide  the  mouse.  */ 


/*  all  the  mouse  messages  from  */ 
/*  WM_MOUSEFIRST  to  */ 
/*  WM_BUTT0N3DBLCLK  inclusive.  */ 

/*  If  there  has  been  any  mouse  */ 
/*  activity,  show  the  mouse.  */ 


WinShowPointer(hwnd, FALSE) ; 

WinWaitMsg (hab, 

WM_MOUSEFIRST, 
WM_BUTT0N3DBLCLK) ; 


WinShowPointer (hwnd, TRUE); 
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WinWaitMuxWaitSem  - 
Wait  MuxWait  Semaphore  or  Message 


#define  INCL_WINMESSAGEMGR 


ULONG  WinWaitMuxWaitSem  (HMUX  hmux,  ULONG  uiTimeout,  PULONG  pUser) 


WinWaitMuxWaitSem  waits  for  a muxwait  semaphore  to  clear  or  for  a Presentation  Manager 
message. 

Parameters 

hmux  (HMUX)  - input 

The  handle  of  the  muxwait  semaphore  to  wait  for. 
uiTimeout  (ULONG)  - input 

The  time-out  in  milliseconds.  This  is  the  maximum  amount  of  time  the  user  wants  to  allow  the 
thread  to  be  blocked. 

This  parameter  can  also  have  the  following  values: 

Value  Definition 

0 (SEM_IMMEDIATE_RETURN)  WinWaitMuxWaitSem  returns  without  blocking  the 

calling  thread. 

—1  (SEM_INDEFINITE_WAIT)  WinWaitMuxWaitSem  blocks  the  calling  thread 

indefinitely. 

pUser  (PULONG)  - output 

A pointer  to  receive  the  user  field  (from  the  muxwait  semaphore  data  structure)  of  the 
semaphore  that  was  posted  or  released. 

If  DCMW_WAIT_ANY  was  specified  in  the  flAttr  parameter  when  the  muxwait  semaphore  was 
created,  this  will  be  the  user  field  of  the  semaphore  that  was  posted  or  released.  If  the  muxwait 
semaphore  consists  of  mutex  semaphores,  any  mutex  semaphore  that  is  released  is  owned  by 
the  caller. 

If  DCMW_WAIT_ALL  was  specified  in  the  flAttr  parameter  when  the  muxwait  semaphore  was 
created,  this  will  be  the  user  field  of  the  last  semaphore  that  was  posted  or  released.  (If  the 
thread  did  not  block,  the  last  semaphore  that  was  posted  or  released  will  also  be  the  last 
semaphore  in  the  muxwait-semaphore  list.)  If  the  muxwait  semaphore  consists  of  mutex 
semaphores,  all  of  the  mutex  semaphores  that  are  released  are  owned  by  the  caller. 


Returns 

Return  Code. 

WinWaitMuxWaitSem  returns  the  following  values: 

0 NO_ERROR 

6 ERROR_INVALID_HANDLE 

8 ERROR_NOT_ENOUGH_MEMORY 

87  ERROR_INVALID_PARAMETER 

95  ERRORJNTERRUPT 

103  ERROR_TOO_MANY_SEM_REQUESTS 

105  ERROR_SEM_OWNER_DIED 

286  ERROR_EMPTY_MUXWAIT 

287  ERROR_MUTEX_OWNED 

292  ERROR_WRONG_TYPE 

640  ERROR_TIMEOUT 
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WinWaitMuxWaitSem  - 

Wait  MuxWait  Semaphore  or  Message 


Remarks 

WinWaitMuxWaitSem  is  similar  to  DosWaitMuxWaitSem  and  enables  a thread  to  wait  for  a muxwait 
semaphore  to  clear  or  for  a window  message  sent  by  the  WinSendMsg  function  from  another  thread 
to  be  received. 

This  function  can  be  issued  by  any  thread  in  the  process  that  created  the  semaphore.  Threads  in 
other  processes  can  also  issue  this  function,  but  they  must  first  gain  access  to  the  semaphore  by 
issuing  DosOpenMuxWaitSem. 

Since  the  processing  of  a window  message  may  take  longer  than  the  value  specified  by  the 
ulTimeout  parameter,  this  function  may  not  return  within  the  time  specified  by  that  value. 


Related  Functions 

• WinSendMsg 

• WinPostMsg 

Example  Code 

This  example  waits  for  a muxwait  semaphore  to  clear.  Assume  that  the  handle  of  the  semaphore  has 
been  placed  into  hmux  already. 

ulTimeout  is  the  number  of  milliseconds  that  the  calling  thread  will  wait  for  the  muxwait  semaphore 
to  clear.  If  the  specified  muxwait  semaphore  is  not  cleared  during  this  time  interval,  the  request 
times  out. 

Idefine  INCL_DOSSEMAPHORES  /*  Semaphore  values  */ 

Idefine  INCL_WINMESSAGEMGR 
linclude  <os2.h> 
linclude  <stdio.h> 

lifndef  ERRORJTMEOUT 

Idefine  ERRORJTMEOUT  640 
Idefine  ERRORJNTERRUPT  95 
lendif 

HMUX  hmux;  /*  Muxwait  semaphore  handle  */ 

ULONG  ulTimeout;  /*  Number  of  milliseconds  to  wait  */ 

ULONG  ulUser;  /*  User  field  for  the  semaphore  that  was 

posted  or  released  (returned)  */ 

ULONG  rc;  /*  Return  code  */ 

ulTimeout  = 60000;  /*  Wait  for  a maximum  of  1 minute  */ 

rc  = WinWaitMuxWaitSem(hmux,  ulTimeout,  iulUser); 

/*  On  successful  return,  the  ulUser  */ 

/*  variable  contains  the  user  */ 

/*  identifier  of  the  semaphore  */ 

/*  that  caused  the  wait  to  */ 

/*  terminate.  If  the  caller  had  */ 

/*  to  wait  for  all  the  semaphores  */ 

/*  within  the  muxwait  semaphore  to  */ 

/*  clear,  then  the  value  corresponds  */ 

/*  to  the  last  semaphore  within  the  */ 

/*  muxwait  semaphore  to  clear.  If  */ 

/*  the  caller  had  to  wait  for  any  */ 

/*  semaphore  with  the  muxwait  */ 

/*  semaphore  to  clear,  then  the  */ 

/*  value  corresponds  to  that  */. 

/*  semaphore.  */ 

if  (rc  ==  ERROR JIMEOUT) 
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WinWaitMuxWaitSem  - 
Wait  MuxWait  Semaphore  or  Message 


{ 

printf( "WinWaitMuxWaitSem  call  timed  out"); 
return; 

} 

if  (rc  ==  ERROR_INTERRUPT) 

{ 

printf( "WinWaitMuxWaitSem  call  was  interrupted"); 
return; 

} 

if  (rc  !=  0) 

{ 

printf( "WinWaitMuxWaitSem  error:  return  code  = %ld",  rc); 
return; 

} 
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WinWindowFromDC  - 

Query  Window  Handle  From  Device  Context 


#define  INCL_WINWINDOWMGR  /*  Or  use  INCL_WIN  or  INCL_PM  */ 


HWND  WinWindowFromDC  (HDC  hdc) 


This  function  returns  the  handle  of  the  window  corresponding  to  a particular  device  context. 

Parameters 

hdc  (HDC)  - input 

Device-context  handle. 

The  device  context  must  first  be  opened  by  the  WinOpenWindowDC  function. 

Returns 

Window  handle: 

NULLHANDLE  Error  occurred.  For  example,  the  device  context  has  not  been  opened  by  the 
WinOpenWindowDC  function. 

Other  Window  handle. 

Possible  returns  from  WinGetLastError 

PMERR  INV  HPS  An  invalid  presentation-space  handle  was  specified. 

PMERR_INV_HDC  An  invalid  device-context  handle  or  (micro  presentation 

space)  presentation-space  handle  was  specified. 


Related  Functions 

• WinEnableWindow 

• WinlsThreadActive 

• WinlsWindow 

• WinlsWindowEnabled 

• WinQueryDesktopWindow 

• WinQueryObjectWindow 

• WinQueryWindowDC 

• WinQueryWindowProcess 

• WinQueryWindowRect 

• WinWindowFromID 

• WinWindowFromPoint 
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WinWindowFromDC  - 
Query  Window  Handle  From  Device  Context 


Example  Code 

If  a device  context  handle  is  specified,  this  example  determines  which  window  is  associated  with  that 
device  context. 

Idefine  INCL_WINWINDOWMGR 
linclude  <0S2.H> 

HWND  hwnd; 

HDC  hdc; 

/*  Assume  the  device  context  for  a window  has  been  opened  in  */ 

*/ 

*/ 

*/ 

*/ 


hwnd  = WinWindowFromDC (hdc) ; 


/*  some  other  window  procedure.  We  would  like  to  get 
/*  a handle  to  that  window. 

/*  This  function  is  called  in  some  other  window: 

/*  hdc  = WinOpenWindowDC(hwnd) ; 
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WinWindowFromID  - 

Query  Window  Handle  From  Identifier 


#define  INCL_WINWINDOWMGR  /*  Or  use  INCL_WIN  or  INCL_PM  */ 


HWND  WinWindowFromID  (HWND  hwndParent,  ULONG  ulldentifier) 


This  function  returns  the  handle  of  the  child  window  with  the  specified  identity. 


Parameters 

hwndParent  (HWND)  - input 
Parent-window  handle. 

ulldentifier  (ULONG)  - input 
Identity  of  the  child  window. 


Returns 

Window  handle: 

NULLHANDLE  No  child  window  of  the  specified  identity  exists 
Other  Child-window  handle. 

Possible  returns  from  WinGetLastError 

PMERR  INVALID  HWND  An  invalid  window  handle  was  specified. 

Remarks 

To  obtain  the  window  handle  for  an  item  within  a dialog  box,  set  hwndParent  to  the  dialog-box 
window’s  handle,  and  set  ulidentifier  to  the  identity  of  the  item  in  the  dialog  template. 


Related  Functions 

• WinEnableWindow 

• WinlsThreadActive 

• WinlsWindow 

• WinlsWindowEnabled 

• WinQueryDesktopWindow 

• WinQueryObjectWindow 

• WinQueryWindowDC 

• WinQueryWindowProcess 

• WinQueryWindowRect 

• WinWindowFromDC 

• WinWindowFromPoint 
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WinWindowFromID  - 
Query  Window  Handle  From  Identifier 


Example  Code 

This  example  calls  WinWindowFromID  to  get  the  window  handle  of  the  system  menu  and  calls 
WinSendMsg  to  send  a message  to  disable  the  Close  menu  item. 

Idefine  INCL_WINFRAMEMGR  /*  for  FID_  definitions.  */ 

Idefine  INCLJIINMENUS  /*  for  MIA_  definitions.  */ 

Idefine  INCLJIINWINDOWMGR 
linclude  <0S2.H> 

HWND  hwndSysMenu,  hwndDlg; 

hwndSysMenu  = WinWindowFromID(hwndDlg,  FID_SYSMENU) ; 

WinSendMsg  (hwndSysMenu,  MMJETITEMATTR, 

MPFR0M2SH0RT(SC_CL0SE,  TRUE), 

MPFR0M2SH0RT(MIA_DISABLED,  MIA_DISABLED)) ; 


Chapter  8.  Window  Functions  8-575 


WinWindowFromPoint 
Window  From  Point 


#define  INCL_WINWINDOWMGR  /*  Or  use  INCL_WIN  or  INCL_PM  */ 


HWND  WinWindowFromPoint  (HWND  hwndParent,  PPOINTL  pptIPoint,  BOOL  (EnumChlldren) 


This  function  finds  the  window  below  a specified  point,  that  is  a descendant  of  a specified  window. 

Parameters 

hwndParent  (HWND)  - input 

Window  handle  whose  child  windows  are  to  be  tested: 

HWNDDESKTOP  The  desktop-window  handle,  implying  that  all  main  windows  are  tested.  In 
this  instance,  pptIPoint  must  be  relative  to  the  bottom  left  corner  of  the 
screen. 

Other  Parent-window  handle. 

pptIPoint  (PPOINTL)  - input 
The  point  to  be  tested. 

Specified  in  window  coordinates  relative  to  the  window  specified  by  the  hwndParent  parameter. 

f EnumChlldren  (BOOL)  - input 
Test  control: 

TRUE  Test  all  the  descendant  windows,  including  child  windows  of  child  windows 
FALSE  Test  only  the  immediate  child  windows. 

Returns 

Window  handle  beneath  pptIPoint : 

NULLHANOLE  pptIPoint  is  outside  hwndParent 

Parent  pptIPoint  is  not  inside  any  of  the  children  of  hwndParent 

Other  Window  handle  is  beneath  pptIPoint. 

Possible  returns  from  WinGetLastError 

PMERR  INVALID  HWND  An  invalid  window  handle  was  specified. 

Remarks 

This  function  checks  only  the  descendants  of  the  specified  window. 


Related  Functions 

• WinEnableWindow 

• WinlsThreadActive 

• WinlsWindow 

• WinlsWindowEnabled 

• WinQueryDesktopWindow 

• WinQueryObjectWindow 

• WinQueryWindowDC 

• WinQueryWindowProcess 

• WinQueryWindowRect 

• WinWindowFromDC 

• WinWindowFromID 
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WinWindowFromPoint  - 
Window  From  Point 


Example  Code 

This  example  calls  WinWindowFromPoint  to  find  out  if  any  main  windows  are  beneath  point  100,100. 

Idefine  INCL_WINWINDOWMGR 
linclude  <0S2.H> 

HWND  hwndunderneath; 

POINTL  point  = { 10OL,  100L}; 

hwndunderneath  = WinWindowFromPoint(HWND_DESKTOP, 

&point, 

FALSE);  /*  do  not  test  the  */ 

/*  descendents  of  */ 

/*  the  main  */ 

/*  windows.  */ 
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Chapter  9.  Workplace  Classes,  Instance  Methods,  and 
Class  Methods 


The  following  sections  contain  Workplace  classes,  instance  methods,  and  class  methods.  Each 
section  is  in  alphabetical  order. 


These  sections  contain  technical  reference  information.  See  the  workplace  chapter  in  the 
Application  Design  Guide  for  workplace  guide  information.  For  information  on  the  System  Object 
Model  (SOM),  see  System  Object  Model  Guide  and  Reference. 


The  following  is  some  terminology  used  in  these  sections: 


class 


class  method 


Inheritance 


Instance 

Instance  method 
In-use  emphasis 

In-use  list 
metaclass 


method 


object 


object  definition 
object  Instance 
subclass 
superclass 


A way  of  categorizing  objects  based  on  their  behavior  and  shape.  A class 
is,  in  effect,  a definition  of  a generic  object.  In  SOM,  a class  is  a special 
kind  of  object  that  can  manufacture  other  objects  that  all  have  a common 
shape  and  exhibit  similar  behavior  (more  precisely,  all  of  the  objects 
manufactured  by  a class  have  the  same  memory  layout  and  share  a 
common  set  of  methods).  New  classes  can  be  defined  in  terms  of  existing 
classes  through  a technique  known  as  inheritance. 

A class  method  of  class  <X>  is  a method  provided  by  the  metaclass  of 
class  <X> . Class  methods  are  executed  without  requiring  any  instances  of 
class  <X>  to  exist,  and  are  frequently  used  to  create  instances. 

The  technique  of  specifying  the  shape  and  behavior  of  one  class  (called  a 
subclass)  as  incremental  differences  from  another  class  (called  the  parent 
class  or  superclass).  The  subclass  inherits  the  superclass's  state 
representation  and  methods,  and  can  provide  additional  data  elements  and 
methods.  The  subclass  also  can  provide  new  functions  with  the  same 
method  names  used  by  the  superclass.  Such  a subclass  method  is  said  to 
override  the  superclass  method,  and  will  be  selected  automatically  by 
method  resolution  on  subclass  instances.  An  overriding  method  can  elect  to 
call  upon  the  superclass's  method  as  part  of  its  own  implementation. 

(Or  object  instance).  A specific  object,  as  distinguished  from  the  abstract 
definition  of  an  object  referred  to  as  its  class. 

A method  valid  for  a particular  object. 

A visual  queue  around  an  object's  icon  to  indicate  that  one  or  more  view 
windows  are  currently  open. 

A linked  list  of  items  representing  resources  allocated  on  an  object's  behalf. 
A class  whose  instances  are  all  classes.  In  SOM,  any  class  descended  from 
SOMCIass  is  a metaclass.  The  methods  of  a metaclass  are  sometimes 
called  “class”  methods. 

One  of  the  units  that  makes  up  the  behavior  of  an  object.  A method  is  a 
combination  of  a function  and  a name,  such  that  many  different  functions 
can  have  the  same  name.  Which  function  the  name  refers  to  at  any  point  in 
time  depends  on  the  object  that  is  to  execute  the  method  and  is  the  subject 
of  method  resolution. 

The  elements  of  data  and  function  that  programs  create,  manipulate,  pass 
as  arguments,  and  so  forth.  An  object  is  a way  of  associating  specific  data 
values  with  a specific  set  of  named  functions  (called  methods)  for  a period 
of  time  (referred  to  as  the  lifetime  of  the  object).  The  data  values  of  an 
object  are  referred  to  as  its  state.  In  SOM,  objects  are  created  by  other 
objects  called  classes.  The  specification  of  what  comprises  the  set  of 
functions  and  data  elements  that  make  up  an  object  is  referred  to  as  the 
definition  of  a class. 

SOM  objects  offer  a high  degree  of  encapsulation.  This  property  permits 
many  aspects  of  the  implementation  of  an  object  to  change  without  affecting 
client  programs  that  depend  on  the  object's  behavior. 

See  class. 

See  instance. 

A class  that  inherits  from  another  class.  See  inheritance. 

A class  from  which  another  class  inherits.  See  inheritance. 
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Workplace  object  classes 

Workplace  objects  are  icons  representative  of  physical  objects  which  users  deal  with  in  the 
workplace.  A Workplace  object  is  implemented  as  an  instance  of  a Workplace  object  class. 
Workplace  object  classes  are  System  Object  Model  (SOM)  object  classes  which  are  descendants  of 
the  predefined  Workplace  object  class,  WPObject.  For  more  information  about  SOM  object  classes, 
see  System  Object  Model  Guide  and  Reference. 

All  Workplace  objects  are  descendants  of  a Workplace  object  storage  class.  Workplace  storage 
object  classes  are  responsible  primarily  for  storing  and  retrieving  object  class  data  for  instances  of 
objects  which  are  descendants  (subclasses)  of  that  storage  class. 

The  three  predefined  Workplace  object  storage  classes  are: 

“WPAbstract”  on  page  9-4  Storage  class  for  objects  stored  in  the  user  profile  ( OS2.INI ) 
“WPFIIeSystem”  on  page  9-14  Storage  class  for  objects  stored  as  files  in  the  file  system 
“WPTranslent”  on  page  9-50  Storage  class  for  non-persistent  objects. 


Workplace  Object  Class  Hierarchy 

The  following  diagram  lists  the  predefined  Workplace  object  classes  in  a hierarchical  order.  Each 
branch  in  the  tree  represents  an  immediate  descendant  (subclass)  of  a Workplace  object  class.  The 
predefined  SOM  object  class,  SOMObject,  is  the  root  class  for  all  SOM  object  classes,  including  all 
Workplace  object  classes. 


CLASS  NAME 


CLASS  DEFINITION  FILE 


SOMObject 

— SOMClass 

— SOMClassMgr 

— "WPObject"  on  page  9-24 

— "WPAbstract"  on  page  9-4 

|—  "WPClock"  on  page  9-5 

— "WPCountry"  on  page  9-8 

— "WPDIsk"  on  page  9-11 

— "WPKeyboard"  on  page  9-22 

— "WPMouse"  on  page  9-23 

— "WPPalette"  on  page  9-27 

— "WPColorPalette"  on  page  9-6 

— "WPFontPalette"  on  page  9-19 

— "WPSchemePalette"  on  page  9-40 

— "WPPrlnter"  on  page  9-31 

— "WPProgram"  on  page  9-34 

— "WPShadow"  on  page  9-41 

— "WPShredder"  on  page  9-43 

— "WPSound"  on  page  9-44 

— "WPSpecial Needs"  on  page  9-45 

— "WPSpooler"  on  page  9-46 

— "WPSystem"  on  page  9-48 

— "WPFIIeSystem"  on  page  9-14 

— "WPDataFile"  on  page  9-9 

— "WPFolder"  on  page  9-16 

(—  "WPDesktop"  on  page  9-10 

— "WPDrives"  on  page  9-13 

— "WPStartup"  on  page  9-47 

— "WPTemplateFolder"  on  page  9-49 
*—  "WPProgramFIle"  on  page  9-37 

— "WPTranslent"  on  page  9-50 

— "WPJob"  on  page  9-21 

— "WPPort"  on  page  9-30 

— "WPPrlnterOriver"  on  page  9-33 

— "WPQueueDriver"  on  page  9-51 


somobj.sc 

somcls.sc 

somcm.sc 

wpobject.se 

wpabs.se 

wpclock.sc 

wpctry.sc 

wpdisk.se 

wpkeybd.se 

wpmouse.se 

wppalet.se 

wpclrpal .sc 

wpfntpal .sc 

wpscheme.se 

wpprint.se 

wppgm. sc 

wpshadow.se 

wpshred.se 

wpsound.se 

wpspneed.se 

wpspool .sc 

wpsystem.se 

wpfsys.se 

wpdataf.se 

wpfolder.se 

wpdesk.se 

wpdrives.se 

wpstart.se 

wptemps.se 

wppgmf.se 

wptrans.se 

wpjob.se 

wpport.se 

wppdr.se 

wpqdr.se 


Figure  9-1.  Class  Hierarchy  for  Predefined  Workplace  Objects 
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Instances  of  some  Workplace  object  classes  cannot  be  created  as  a Workplace  object.  These 
classes  are  provided  as  base  classes  which  provide  support  for  descendant  classes  that  can  have 
instances  created.  Other  classes  are  SOM  classes  and  are  described  in  better  detail  in  the  System 
Object  Model  Guide  and  Reference. 

These  classes  include: 

SOMObject  This  is  the  SOM  root  class,  all  SOM  classes  must  be  descended  from 

SOMObject.  A Workplace  object  of  this  class  cannot  be  created. 
SOMCiass  This  is  the  SOM  metaclass,  that  is,  the  instances  of  this  class  are  class 

objects.  A Workplace  object  of  this  class  cannot  be  created. 

SOMCiassMgr  This  is  the  SOM  class  manager  class.  A Workplace  object  of  this  class 

cannot  be  created. 
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WP  Abstract 


Class  definition  file:wpabs.sc 
Class  hierarchy 

SOMObject 

WPObject 

WP  Abstract 

Description 

This  is  the  abstract  object  storage  class.  The  storage  medium  for  objects  that  are  descendants  of  the 
WPAbstract  class  is  the  INI  file.  In  other  words,  any  object  class  derived  from  WPAbstract  will  have 
persistent  storage  for  its  instance  variables  in  the  INI  file.  Note  that  an  abstract  object  does  not  have 
a file  name,  just  a numeric  handle  that  can  be  used  to  identify  it.  An  instance  of  this  class  can  be 
created  as  a Workplace  object.  There  are  no  instances  of  this  class  initially  created  by  the  system. 


Instance  methods 

There  are  currently  no  methods  defined  for  the  WPAbstract  Workplace  object  class. 

WPObject  instance  methods 

The  following  list  shows  all  the  methods  overridden  by  the  WPAbstract  class.  These  methods  are 
overridden  in  order  to  modify  the  behavior  defined  by  an  ancestor  class. 

• “wpCopyObject  - WPObject  instance  method"  on  page  9-105 

• “wpCreateFromTemplate  - WPObject  instance  method”  on  page  9-106 

• “wpSavelmmediate  - WPObject  instance  method”  on  page  9-198 

• “wpSaveState  - WPObject  instance  method"  on  page  9-200 

• “wpRestoreState  - WPObject  instance  method”  on  page  9-194 

• “wpMoveObject  - WPObject  instance  method"  on  page  9-141 

• “wpQuerylconData  - WPObject  instance  method”  on  page  9-170 

• “wpSetlconData  - WPObject  instance  method”  on  page  9-218 

• “wpSetTitle  - WPObject  instance  method"  on  page  9-227 


Class  methods 

The  following  shows  the  class  methods  overridden  by  the  WPAbstract  class.  These  methods  are 
overridden  to  modify  the  behavior  defined  by  an  ancestor  class. 

WPObject  class  methods 

• “wpcisQuery Title  - WPObject  class  method”  on  page  9-268 
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WPCIock 


Class  definition  file:wpclock.sc 
Class  hierarchy 

SOMObject 

WPObject 

WPAbstract 

WPCIock 

Description 

This  is  the  system  clock  object  class.  An  instance  of  this  class  can  be  created  as  a Workplace  object. 
An  instance  of  this  class  is  created  initially  by  the  system.  It  has  the  title,  “System  Clock”  and 
resides  in  the  “System  Setup"  folder. 

Instance  methods 

The  following  list  shows  all  the  WPCIock  instance  methods. 

• “wpAddClockAlarmPage  - WPCIock  instance  method”  on  page  9-53 

• “wpAddClockDateTimePage  - WPCIock  instance  method”  on  page  9-54 

• “wpAddClockViewIPage  - WPCIock  instance  method"  on  page  9-55 

• “wpAddClockView2Page  - WPCIock  instance  method”  on  page  9-56 

WPObject  instance  methods 

The  following  list  shows  all  the  methods  overridden  by  the  WPCIock  class.  These  methods  are 
overridden  in  order  to  modify  the  behavior  defined  by  an  ancestor  class. 

• “wpAddSettingsPages  - WPObject  instance  method”  on  page  9-89 

• “wpFilterPopupMenu  - WPObject  instance  method”  on  page  9-123 

• “wpQueryDefauitView  - WPObject  instance  method”  on  page  9-160 

• “wpOpen  - WPObject  instance  method”  on  page  9-142 

• “wpModifyPopupMenu  - WPObject  instance  method”  on  page  9-140 

• “wpMenultemHelpSelected  - WPObject  instance  method”  on  page  9-138 

• “wpMenultemSelected  - WPObject  instance  method"  on  page  9-139 

• “wpSaveState  - WPObject  instance  method”  on  page  9-200 

• “wpRestoreState  - WPObject  instance  method”  on  page  9-194 

Class  methods 

The  following  list  shows  all  the  class  methods  overridden  by  the  WPCIock  class.  These  methods  are 
overridden  to  modify  the  behavior  defined  by  an  ancestor  class. 

WPObject  class  methods 

• “wpcisQueryDefauitView  - WPObject  class  method"  on  page  9-252 

• “wpcIsQuerylconData  - WPObject  class  method”  on  page  9-261 

• “wpcIsQueryStyle  - WPObject  class  method”  on  page  9-267 

• “wpcIsQuery Title  - WPObject  class  method"  on  page  9-268 
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WPColorPalette 


Class  definition  file:wpclrpal.sc 
Class  hierarchy 

SOMObject 

WPObject 

WPAbstract 

WPPalette 

WPColorPalette 


Description 

This  is  the  color  palette  object  class.  An  instance  of  this  class  can  be  created  as  a Workplace  object. 
An  instance  of  this  class  is  created  initially  by  the  system.  It  has  the  title,  “Color  Palette”  and 
resides  in  the  “System  Setup”  folder. 


Instance  methods 

There  are  currently  no  methods  defined  for  the  WPColorPalette  Workplace  object  class. 

WPObject  instance  methods 

The  following  list  shows  all  the  methods  overridden  by  the  WPColorPalette  class.  These  methods 
are  overridden  in  order  to  modify  the  behavior  defined  by  an  ancestor  class. 

• “wpMenultemHelpSelected  - WPObject  instance  method”  on  page  9-138 

• “wpSetup  - WPObject  instance  method”  on  page  9-229 

These  are  the  keyname  - value  pairs  added  by  WPColorPalette  class. 


KEYNAME 

VALUE 

Description 

COLORS 

RGB  values 

These  are  the  initial  color  values  of  each  cell  in 
the  color  palette.  The  values  for  each  cell  are 
separated  by  commas.  This  is  equivalent  to 
calling  the  wpSetupCell  method.  The  RGB  value 
must  be  presented  as  a 6- digit  hex  value  in  the 
format  OxRRGGBB  where  RR.GG,  and  BB  are  the 
red,  green  and  blue,  respectively,  values  ranging 
between  00  and  FF  (0  - 255). 

Example 

pszSetupString="COLORS=0x000000,0xFFFFFF,0xFF23B4 
0x505050 , 0X0OFFFF, 0XA0A0A0 " 


WPPalette  methods 

• “wpDragCell  - WPPalette  instance  method”  on  page  9-115 

• “wpEditCell  - WPPalette  instance  method”  on  page  9-121 

• “wpPaintCell  - WPPalette  instance  method”  on  page  9-143 

• “wpQueryPaletteHelp  - WPPalette  instance  method”  on  page  9-173 
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Class  methods 

The  following  list  shows  all  the  class  methods  overridden  by  the  WPColorPalette  class.  These 
methods  are  overridden  to  modify  the  behavior  defined  by  an  ancestor  class. 

WPObject  class  methods 

• “wpcIsQueryDefaultHelp  - WPObject  class  method”  on  page  9-251 

• “wpcIsQueryStyle  - WPObject  class  method”  on  page  9-267 

• “wpcIsQueryTitle  - WPObject  class  method”  on  page  9-268 

WPPalette  class  methods 

• “wpcIsQueryEditString  - WPPalette  class  method”  on  page  9-257 
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WPCountry 


Class  definition  file:wpctry.sc 
Class  hierarchy 

SOMObject 
WPObject 
WP  Abstract 

WPCountry 


Description 

This  is  the  country  object  class.  An  instance  of  this  class  can  be  created  as  a Workplace  object.  An 
instance  of  this  class  is  created  initially  by  the  system.  It  has  the  title,  “Country”  and  resides  in  the 
“System  Setup”  folder. 


Instance  methods 

The  following  list  shows  all  of  the  WPCountry  instance  methods. 

• “wpAddCountryDatePage  - WPCountry  instance  method”  on  page  9-57 

• “wpAddCountryNumbersPage  - WPCountry  instance  method”  on  page  9-58 

• “wpAddCountryPage  - WPCountry  instance  method”  on  page  9-59 

• “wpAddCountryTimePage  - WPCountry  instance  method"  on  page  9-60 

WPObject  instance  methods 

The  following  list  shows  all  of  the  methods  overridden  by  the  WPCountry  class.  These  methods  are 
overridden  in  order  to  modify  the  behavior  defined  by  an  ancestor  class. 

• “wpAddSettingsPages  - WPObject  instance  method”  on  page  9-89 

• “wpFilterPopupMenu  - WPObject  instance  method"  on  page  9-123 

• “wpInitData  - WPObject  instance  method”  on  page  9-133 

• “wpQueryDefaultHelp  - WPObject  instance  method"  on  page  9-159 

• “wpQueryDefauItView  - WPObject  instance  method”  on  page  9-160 

Class  methods 

The  following  list  shows  all  the  class  methods  overridden  by  the  WPCountry  class.  These  methods 
are  overridden  to  modify  the  behavior  defined  by  an  ancestor  class. 

WPObject  class  methods 

• “wpcIsQueryDefaultHelp  - WPObject  class  method”  on  page  9-251 

• “wpcIsQueryDefauItView  - WPObject  class  method"  on  page  9-252 

• “wpcIsQuerylconData  - WPObject  class  method”  on  page  9-261 

• “wpcIsQueryStyle  - WPObject  class  method”  on  page  9-267 

• “wpcIsQueryTitle  - WPObject  class  method”  on  page  9-268 
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WPDataFile 


Class  definition  file:wpdataf.sc 
Class  hierarchy 

SOMObject 

WPObject 

WPFileSystem 

WPDataFile 


Description 

This  is  the  data  file  object  class.  An  instance  of  this  class  can  be  created  as  a Workplace  object  and 
is  created  initially  by  the  system  in  its  template  form.  It  has  the  title,  “ Data  file”  and  resides  in  the 
“Templates”  folder. 


Instance  methods 

The  following  shows  all  the  WPDataFile  methods. 

• “wpAddFileTypePage  - WPDataFile  instance  method”  on  page  9-66 

• “wpPrintMetaFile  - WPDataFile  instance  method”  on  page  9-146 

• “wpPrintPifFile  - WPDataFile  instance  method”  on  page  9-148 

• “wpPrintPlainTextFile  - WPFileSystem  instance  method"  on  page  9-149 

• “wpPrintPrinterSpecificFile  - WPDataFile  instance  method"  on  page  9-150 

• “wpPrintUnknownFile  - WPDataFile  instance  method”  on  page  9-151 

WPObject  instance  methods 

The  following  list  shows  all  the  methods  overridden  by  the  WPDataFile  class.  These  methods  are 
overridden  in  order  to  modify  the  behavior  defined  by  an  ancestor  class. 

• “wpAddSettingsPages  - WPObject  instance  method”  on  page  9-89 

• “wpFormatDragltem  - WPObject  instance  method”  on  page  9-126 

• “wpinitData  - WPObject  instance  method”  on  page  9-133 

• “wpMenultemHelpSelected  - WPObject  instance  method”  on  page  9-138 

• “wpMenultemSelected  - WPObject  instance  method”  on  page  9-139 

• “wpModifyPopupMenu  - WPObject  instance  method”  on  page  9-140 

• “wpOpen  - WPObject  instance  method”  on  page  9-142 

• “wpPrintObject  - WPObject  instance  method”  on  page  9-147 

• “wpQueryDefaultHelp  - WPObject  instance  method”  on  page  9-159 

• “wpRestoreState  - WPObject  instance  method"  on  page  9-194 

• “wpSaveState  - WPObject  instance  method”  on  page  9-200 

• “wpUnlnitData  - WPObject  instance  method”  on  page  9-238 


Class  methods 

The  following  list  shows  all  the  class  methods  overridden  by  the  WPDataFile  class.  These  methods 
are  overridden  to  modify  the  behavior  defined  by  an  ancestor  class. 

WPObject  class  methods 

• “wpcIsQueryDefaultHelp  - WPObject  class  method”  on  page  9-251 

• “wpcisQueryDefauItView  - WPObject  class  method”  on  page  9-252 

• “wpcisQuerylconData  - WPObject  class  method"  on  page  9-261 

• “wpcisQueryStyle  - WPObject  class  method”  on  page  9-267 

• “wpcisQueryTitle  - WPObject  class  method”  on  page  9-268 
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WPDesktop 


Class  definition  file:wpdesk.sc 
Class  hierarchy 

SOMObject 

WPObject 

WPFileSystem 

WPFolder 

WPDesktop 


Description 

This  is  the  Workplace  desktop  object  class.  An  instance  of  this  class  can  be  created  as  a Workplace 
object.  An  instance  of  this  class  is  created  initially  by  the  system.  It  has  the  title,  “OS/2  Desktop” 
and  resides  in  the  root  directory  of  the  drive  containing  the  user  profile. 


Instance  methods 

The  following  table  shows  all  the  WPDesktop  methods. 

• “wpAddDesktopLockupIPage  - WPDesktop  instance  method”  on  page  9-61 

• “wpAddDesktopLockup2Page  - WPDesktop  instance  method”  on  page  9-62 

• “wpAddDesktopLockup3Page  - WPDesktop  instance  method”  on  page  9-63 

• “wpisCurrentDesktop  - WPDesktop  instance  method”  on  page  9-137 

WPObject  instance  methods 

The  following  list  shows  all  the  methods  overridden  by  the  WPDesktop  class.  These  methods  are 
overridden  in  order  to  modify  the  behavior  defined  by  an  ancestor  class. 

• “wpAddSettingsPages  - WPObject  instance  method”  on  page  9-89 

• “wpFilterPopupMenu  - WPObject  instance  method"  on  page  9-123 

• “wpMenultemSelected  - WPObject  instance  method”  on  page  9-139 

• “wpModifyPopupMenu  - WPObject  instance  method”  on  page  9-140 

Class  methods 

The  following  list  shows  all  the  class  methods  overridden  by  the  WPDesktop  class.  These  methods 
are.  overridden  to  modify  the  behavior  defined  by  an  ancestor  class. 

WPObject  class  methods 

• “wpcIsQueryDefaultHelp  - WPObject  class  method”  on  page  9-251 

• “wpcisQuerylconData  - WPObject  class  method”  on  page  9-261 

• “wpcisQueryStyle  - WPObject  class  method”  on  page  9-267 

• “wpcisQueryTitle  - WPObject  class  method”  on  page  9-268 
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WPDisk 


Class  definition  file:wpdisk.sc 
Class  hierarchy 

SOMObject 

WPObject 

WPAbstract 

WPDisk 

Description 

This  is  the  file  system  device  object  class.  It  is  used  to  represent  all  types  of  file  system  devices 
including: 

• CD  ROM  drives 

• Fixed  disk  drives 

• Floppy  diskette  drives 

• Magnetic  tape  drives 

• Network  drives 

• Ram  drives 

An  instance  of  this  class  can  be  created  as  a Workplace  object.  Shadow  instances  of  this  class  are 
created  initially  by  the  system  for  each  file  system  device  available.  Each  instance  has  a title 
corresponding  to  a file  system  device  and  resides  in  the  Drives  folder.  If  a primary  local  removable 
media  file  system  device  such  as  a floppy  drive  exists,  an  instance  of  this  class  will  also  be  created 
on  the  desktop,  which  will  represent  this  drive.  These  instances  actually  appear  as  WPShadow 
objects  which  are  shadows  of  WPDisk  objects. 


Instance  methods 

The  following  shows  the  WPDisk  methods. 

• “wpAddDiskDetailsPage  - WPDisk  instance  method”  on  page  9-64 

• “wpQueryLogicalDrive  - WPDisk  instance  method”  on  page  9-171 

• “wpQueryRootFolder  - WPDisk  instance  method”  on  page  9-179 

WPObject  instance  methods 

The  following  list  shows  all  the  methods  overridden  by  the  WPDisk  class.  These  methods  are 
overridden  in  order  to  modify  the  behavior  defined  by  an  ancestor  class. 

• “wpAddSettingsPages  - WPObject  instance  method”  on  page  9-89 

• “wpDragOver  - WPObject  instance  method”  on  page  9-118 

• “wpDrop  - WPObject  instance  method”  on  page  9-119 

• “wpFilterPopupMenu  - WPObject  instance  method”  on  page  9-123 

• “wpMenultemFlelpSelected  - WPObject  instance  method”  on  page  9-138 

• “wpMenultemSelected  - WPObject  instance  method”  on  page  9-139 

• “wpModifyPopupMenu  - WPObject  instance  method”  on  page  9-140 

• “wpOpen  - WPObject  instance  method”  on  page  9-142 

• “wpRestoreState  - WPObject  instance  method”  on  page  9-194 

• “wpSaveState  - WPObject  instance  method”  on  page  9-200 

• “wpSetTitle  - WPObject  instance  method”  on  page  9-227 
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Class  methods 

The  following  list  shows  all  the  class  methods  overridden  by  the  WPDisk  class.  These  methods  are 
overridden  to  modify  the  behavior  defined  by  an  ancestor  class. 

WPObject  class  methods 

• “wpcIsQueryDefaultHelp  - WPObject  class  method”  on  page  9-251 

• “wpcIsQueryDefauItView  - WPObject  class  method”  on  page  9-252 

• “wpcIsQuerylconData  - WPObject  class  method"  on  page  9-261 

• “wpcIsQueryStyle  - WPObject  class  method”  on  page  9-267 
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WPDrives 


Class  definition  file:wpdrives.sc 
Class  hierarchy 

SOMObject 

WPObject 

WPFileSystem 

WPFolder 

WPDrives 

Description 

This  is  the  file  system  device  folder  object  class.  An  instance  of  this  class  can  be  created  as  a 
Workplace  object.  An  instance  of  this  class  is  created  initially  by  the  system.  It  has  the  title, 

“Drives”  and  resides  in  the  “OS/2  System”  folder. 

Methods 

There  are  currently  no  methods  defined  for  the  WPDrives  Workplace  object  class. 

WPObject  methods 

The  following  list  shows  all  the  methods  overridden  by  the  WPDrives  class.  These  methods  are 
overridden  in  order  to  modify  the  behavior  defined  by  an  ancestor  class. 

• “wpFilterPopupMenu  - WPObject  instance  method”  on  page  9-123 

• “wpMenultemHelpSelected  - WPObject  instance  method”  on  page  9-138 

• “wpMenultemSelected  - WPObject  instance  method”  on  page  9-139 

• “wpModifyPopupMenu  - WPObject  instance  method"  on  page  9-140 

• “wpPopulate  - WPFolder  instance  method"  on  page  9-144 

Class  methods 

The  following  list  shows  all  the  class  methods  overridden  by  the  WPDrives  class.  These  methods  are 
overridden  to  modify  the  behavior  defined  by  an  ancestor  class. 

WPObject  class  methods 

• “wpcisQueryDefaultHelp  - WPObject  class  method”  on  page  9-251 

• “wpcisQuerylconData  - WPObject  class  method”  on  page  9-261 

• “wpcisQueryStyle  - WPObject  class  method”  on  page  9-267 

• “wpcisQueryTitle  - WPObject  class  method"  on  page  9-268 
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WPFileSystem 


Class  definition  file:wpfsys.sc 
Class  hierarchy 

SOMObject 

WPObject 

WPFileSystem 

Description 

This  is  the  file  system  object  storage  class.  WPFileSystem  is  the  storage  class  that  represents  all  file 
system  objects  including  directory  (folder),  data  file,  executable  file,  and  root  directory  (drive) 
objects.  This  class  also  provides  persistent  storage  of  instance  variables  for  all  classes  derived 
from  it.  A Workplace  object  of  this  class  cannot  be  created. 


Instance  methods 

The  following  list  shows  all  the  WPFileSystem  class  methods. 

• “wpAddFileMenuPage  - WPFileSystem  instance  method”  on  page  9-65 

• “wpAddFilelPage  - WPFileSystem  instance  method”  on  page  9-67 

• “wpAddFile2Page  - WPFileSystem  instance  method”  on  page  9-68 

• “wpAddFile3Page  - WPFileSystem  instance  method”  on  page  9-69 

• “wpQueryHandle  - WPObject  instance  method”  on  page  9-168 

• “wpQueryRealName  - WPFileSystem  instance  method"  on  page  9-178 

• “wpQueryType  - WPFileSystem  instance  method”  on  page  9-183 

• “wpSetRealName  - WPFileSystem  instance  method”  on  page  9-224 

• “wpSetType  - WPFileSystem  instance  method”  on  page  9-228 

WPObject  instance  methods 

The  following  list  shows  all  the  methods  overridden  by  the  WPFileSystem  class.  These  methods  are 
overridden  in  order  to  modify  the  behavior  defined  by  an  ancestor  class. 

• “wpAddSettingsPages  - WPObject  instance  method”  on  page  9-89 

• “wpCopyObject  - WPObject  instance  method”  on  page  9-105 

• “wpCreateFromTemplate  - WPObject  instance  method”  on  page  9-106 

• “wpDoesObjectMatch  - WPObject  instance  method”  on  page  9-114 

• “wpDraggedOverObject  - WPObject  instance  method"  on  page  9-116 

• “wpDroppedOnObject  - WPObject  instance  method”  on  page  9-120 

• “wpFilterPopupMenu  - WPObject  instance  method"  on  page  9-123 

• “wpFormatDragltem  - WPObject  instance  method”  on  page  9-126 

• “wpMenultemSelected  - WPObject  instance  method"  on  page  9-139 

• “wpModifyPopupMenu  - WPObject  instance  method”  on  page  9-140 

• “wpMoveObject  - WPObject  instance  method"  on  page  9-141 

• “wpOpen  - WPObject  instance  method"  on  page  9-142 

• “wpQueryDetailsData  - WPObject  instance  method”  on  page  9-161 

• “wpQuerylconData  - WPObject  instance  method”  on  page  9-170 

• “wpRestoreState  - WPObject  instance  method”  on  page  9-194 

• “wpSavelmmediate  - WPObject  instance  method”  on  page  9-198 

• “wpSaveState  - WPObject  instance  method”  on  page  9-200 

• “wpSetlconData  - WPObject  instance  method"  on  page  9-218 

• “wpSetTitle  - WPObject  instance  method”  on  page  9-227 

• “wpUnlnitData  - WPObject  instance  method”  on  page  9-238 
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Class  methods 

The  following  list  shows  the  wpFileSystem  class  methods. 

• “wpcIsQuerylnstanceFilter  - WPFileSystem  class  method”  on  page  9-262 

• “wpcIsQuerylnstanceType  - WPFileSystem  class  method”  on  page  9-263 

WPObject  class  methods 

The  following  list  shows  all  the  class  methods  overridden  by  the  WPFIIeSystem  class.  These 
methods  are  overridden  to  modify  the  behavior  defined  by  an  ancestor  class. 

• “wpcIsInitData  - WPObject  class  method”  on  page  9-246 

• “wpcIsQueryDetailsInfo  - WPObject  class  method”  on  page  9-254 

• “wpcIsQuerylconData  - WPObject  class  method”  on  page  9-261 

• “wpcIsQueryTitle  - WPObject  class  method”  on  page  9-268 
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WPFolder 


Class  definition  file:wpfolder.sc 
Class  hierarchy 

SOMObject 

WPObject 

WPFileSystem 

WPFolder 

Description 

This  is  the  folder  object  class.  An  instance  of  this  class  can  be  created  as  a Workplace  object.  An 
instance  of  this  class  is  created  initially  by  the  system  in  its  template  form.  It  has  the  title  “Folder” 
and  resides  in  the  “Templates”  folder. 


Instance  methods 

The  following  list  shows  how  all  the  WPFolder  methods  are  related  within  functional  areas. 

Settings  notebook  methods 

• “wpAddFolderBackgroundPage  - WPFolder  instance  method”  on  page  9-70 

• “wpAddFolderlncludePage  - WPFolder  instance  method”  on  page  9-71 

• “wpAddFolderSortPage  - WPFolder  instance  method”  on  page  9-72 

• “wpAddFolderViewIPage  — WPFolder  instance  method"  on  page  9-73 

• “wpAddFolderView2Page  - WPFolder  instance  method”  on  page  9-74 

• “wpAddFolderView3Page  - WPFolder  instance  method”  on  page  9-75 

Object  position  methods 

• “wpQueryNextlconPos  - WPFolder  instance  method”  on  page  9-172 

• “wpSetNextlconPos  - WPFolder  instance  method"  on  page  9-219 


Folder  attributes  methods 

• “wpQueryFIdrAttr  - WPFolder  instance  method”  on  page  9-164 

• “wpQueryFIdrDetailsClass  - WPFolder  instance  method"  on  page  9-165 

• “wpQueryFIdrFlags  - WPFolder  instance  method"  on  page  9-166 

• “wpQueryFIdrFont  - WPFolder  instance  method"  on  page  9-167 

• “wpSetFIdrAttr  - WPFolder  instance  method"  on  page  9-213 

• “wpSetFIdrDetailsClass  - WPFolder  instance  method”  on  page  9-214 

• “wpSetFIdrFlags  - WPFolder  instance  method”  on  page  9-215 

• “wpSetFIdrFont  - WPFolder  instance  method”  on  page  9-216 


Folder  state  methods 

• “wphlideFIdrRunObjs  - WPFolder  instance  method”  on  page  9-130 


Folder  content  methods 

• “wpDeleteContents  - WPFolder  instance  method”  on  page  9-110 

• “wpPopulate  - WPFolder  instance  method”  on  page  9-144 

• “wpQuery Content  - WPFolder  instance  method”  on  page  9-158 

• “wpRefresh  - WPFileSystem  instance  method”  on  page  9-185 
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WPObject  instance  methods 

The  following  list  shows  all  the  methods  overridden  by  the  WPFolder  class.  These  methods  are 
overridden  in  order  to  modify  the  behavior  defined  by  an  ancestor  class. 

• “wpAddFile2Page  - WPFileSystem  instance  method”  on  page  9-68 

• “wpAddFile3Page  - WPFileSystem  instance  method"  on  page  9-69 

• “wpAddSettingsPages  - WPObject  instance  method”  on  page  9-89 

• “wpConfirmDelete  - WPObject  instance  method”  on  page  9-103 

• “wpDelete  - WPObject  instance  method”  on  page  9-108 

• “wpDragOver  - WPObject  instance  method”  on  page  9-118 

• “wpDrop  - WPObject  instance  method”  on  page  9-119 

• “wpFilterPopupMenu  - WPObject  instance  method"  on  page  9-123 

• “wpFormatDragltem  - WPObject  instance  method"  on  page  9-126 

• “wpFree  - WPObject  instance  method”  on  page  9-127 

• “wpinitData  - WPObject  instance  method"  on  page  9-133 

• “wpMenultemHelpSelected  - WPObject  instance  method”  on  page  9-138 

• “wpMenultemSelected  - WPObject  instance  method"  on  page  9-139 

• “wpModifyPopupMenu  - WPObject  instance  method”  on  page  9-140 

• “wpMoveObject  - WPObject  instance  method”  on  page  9-141 

• “wpOpen  - WPObject  instance  method”  on  page  9-142 

• “wpRender  - WPObject  instance  method”  on  page  9-189 

• “wpRestoreState  - WPObject  instance  method”  on  page  9-194 

• “wpSaveState  - WPObject  instance  method”  on  page  9-200 

• “wpSetup  - WPObject  instance  method”  on  page  9-229 

• “wpUnlnitData  - WPObject  instance  method”  on  page  9-238 

The  following  table  shows  the  keyname-value  pairs  supported  by  the  WPObject  class. 


KEYNAME 

VALUE 

Description 

OPEN 

ICON 

Open  icon  view  when  object  is 
created  or  when  WinSetObjectData 
is  called. 

TREE 

Open  tree  view  when  object  is 
created  or  when  WinSetObjectData 
is  called. 

DETAILS 

Open  details  view  when  object  is 
created  or  when  WinSetObjectData 
is  called. 

ICONVIEW 

s1[,s2,...sn] 

Set  icon  view  to  the  specified  styles. 

TREEVIEW 

s1[,s2,...sn] 

Set  tree  view  to  the  specified  styles. 

DETAILSVIEW 

s1[,s2,...sn] 

Set  details  view  to  the  specified 
styles. 

view  styles 

FLOWED 

flowed  list  items. 

NONFLOWED 

non-flowed  list  items. 

NONGRID 

non-gridded  icon  view. 

NORMAL 

normal  size  icons. 

MINI 

small  icons. 

INVISIBLE 

no  icons. 

LINES 

lines  in  tree  view. 

NOLINES 

no  lines  in  tree  view. 

BACKGROUND 

filename 

This  sets  the  folder  background. 
filename  is  the  name  of  a file  in  the 
\OS2\BITMAP  directory  of  the  boot 
drive. 
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Class  methods 

The  following  list  shows  all  the  WPFolder  class  methods. 

• “wpcIsQueryOpenFolders  - WPFolder  class  method”  on  page  9-265 

WPObject  class  methods 

The  following  list  shows  all  the  class  methods  overridden  by  the  WPFolder  class.  These  methods  are 
overridden  to  modify  the  behavior  defined  by  an  ancestor  class. 

• “wpcIsQueryDefaultFlelp  - WPObject  class  method”  on  page  9-251 

• “wpcIsQueryDefauItView  - WPObject  class  method”  on  page  9-252 

• “wpcIsQuerylconData  - WPObject  class  method”  on  page  9-261 

• “wpcIsQueryStyle  - WPObject  class  method”  on  page  9-267 

• “wpcIsQueryTitle  - WPObject  class  method”  on  page  9-268 
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WPFontPalette 


Class  definition  fiie:wpfntpal.sc 
Class  hierarchy 

SOMObject 

WPObject 

WPAbstract 

WPPalette 

WPFontPalette 


Description 

This  is  the  font  palette  object  class.  An  instance  of  this  class  can  be  created  as  a Workplace  object. 
An  instance  of  this  class  is  created  initially  by  the  system.  It  has  the  title,  “Font  Palette”  and  resides 
in  the  “System  Setup”  folder. 


Instance  methods 

There  are  currently  no  methods  defined  for  the  WPFontPalette  Workplace  object  class. 

WPObject  instance  methods 

The  following  list  shows  all  the  methods  overridden  by  the  WPFontPalette  class.  These  methods  are 
overridden  in  order  to  modify  the  behavior  defined  by  an  ancestor  class. 

• “wpMenultemHelpSelected  - WPObject  instance  method"  on  page  9-138 

• “wpSetup  - WPObject  instance  method”  on  page  9-229 

The  following  are  the  keyname  - value  pairs  added  by  the  WPFontPalette  class. 


KEYNAME 

VALUE 

Description 

FONTS 

fonttype 

These  are  the  initial  fonts  for  each  cell  in  the  font 
palette.  The  values  for  each  cell  are  separated 
by  commas.  This  is  equivalent  to  calling  the 
wpSetupCell  method.  The  fonttype  value  is 
presented  as  the  point  size  followed  by  a period 
which  is  then  followed  by  the  face  name. 

Example 

pszSetupString="FONTS=10. Helvetica, 8. Helvetica, 10. Courier, 

12 . Cour i er , 24 . Couri er , 10 . System" 

WPPalette  instance  methods 

• “wpDragCell  - WPPalette  instance  method”  on  page  9-115 

• “wpEditCell  - WPPalette  instance  method”  on  page  9-121 

• “wpPaintCell  - WPPalette  instance  method”  on  page  9-143 

• “wpQueryPaletteHelp  - WPPalette  instance  method”  on  page  9-173 

• “wpSetupCell  - WPPalette  instance  method"  on  page  9-233 


Chapter  9.  Workplace  Classes,  Instance  Methods,  and  Class  Methods  9-19 


Class  methods 

The  following  list  shows  all  the  class  methods  overridden  by  the  WPFontPaiette  class.  These 
methods  are  overridden  to  modify  the  behavior  defined  by  an  ancestor  class. 

WPObject  class  methods 

• “wpcIsQueryDefaultHelp  - WPObject  class  method”  on  page  9-251 

• “wpcIsQueryDefauItView  - WPObject  class  method”  on  page  9-252 

• “wpcIsQuerylconData  - WPObject  class  method”  on  page  9-261 

• “wpcIsQueryStyle  - WPObject  class  method”  on  page  9-267 

• “wpcIsQuery Title  - WPObject  class  method”  on  page  9-268 

WPPalette  class  methods 

• “wpcIsQueryEditString  - WPPalette  class  method”  on  page  9-257 
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WPJob 


Class  definition  file:wpjob.sc 
Class  hierarchy 

SOMObject 

WPObject 

WPTransient 

WPJob 


Description 

This  is  the  job  object  class.  An  instance  of  this  class  is  created  by  the  print  object  in  its  icon  or  detail 
view. 

Instance  methods 

The  following  table  shows  all  the  WPJob  methods. 

• “wpDeleteJob  - WPJob  instance  method”  on  page  9-112 

• “wpHoidJob  - WPJob  instance  method”  on  page  9-131 

• “wpPrintJobNext  - WPJob  instance  method”  on  page  9-145 

• “wpReleaseJob  - WPJob  instance  method"  on  page  9-187 

• “wpStartJobAgain  - WPJob  instance  method”  on  page  9-235 

WPObject  instance  methods 

The  following  list  shows  all  the  methods  overridden  by  the  WPJob  class.  These  methods  are 
overridden  in  order  to  modify  the  behavior  defined  by  an  ancestor  class. 

• “wpAddSettingsPages  - WPObject  instance  method”  on  page  9-89 

• “wpCopyObject  - WPObject  instance  method”  on  page  9-105 

• “wpDragOver  - WPObject  instance  method”  on  page  9-118 

• “wpDrop  - WPObject  instance  method"  on  page  9-119 

• “wpFilterPopupMenu  - WPObject  instance  method”  on  page  9-123 

• “wpFree  - WPObject  instance  method”  on  page  9-127 

• “wpinitData  - WPObject  instance  method”  on  page  9-133 

• “wpMenultemHelpSelected  - WPObject  instance  method”  on  page  9-138 

• “wpMenultemSelected  - WPObject  instance  method”  on  page  9-139 

• “wpModifyPopupMenu  - WPObject  instance  method”  on  page  9-140 

• “wpOpen  - WPObject  instance  method”  on  page  9-142 

• “wpSetTitle  - WPObject  instance  method”  on  page  9-227 

• “wpUnlnitData  - WPObject  instance  method”  on  page  9-238 


Class  methods 

The  following  list  shows  all  the  class  methods  overridden  by  the  WPJob  class.  These  methods  are 
overridden  to  modify  the  behavior  defined  by  an  ancestor  class. 

WPObject  class  methods 

• “wpcisQueryDefaultHelp  - WPObject  class  method”  on  page  9-251 

• “wpcisQueryDefauitView  - WPObject  class  method”  on  page  9-252 

• “wpcisQueryDetails  - WPObject  class  method”  on  page  9-253 

• “wpcisQueryDetailsInfo  - WPObject  class  method”  on  page  9-254 

• “wpcisQuerylconData  - WPObject  class  method”  on  page  9-261 

• “wpcisQueryStyle  - WPObject  class  method”  on  page  9-267 

• “wpcisQueryTitle  - WPObject  class  method"  on  page  9-268 


Chapter  9.  Workplace  Classes,  Instance  Methods,  and  Class  Methods 


9-21 


WPKeyboard 


Class  definition  file:wpkeybd.sc 
Class  hierarchy 

SOMObject 

WPObject 

WPAbstract 

WPKeyboard 

Description 

This  is  the  keyboard  object  class.  An  instance  of  this  class  can  be  created  as  a Workplace  object. 

An  instance  of  this  class  is  created  initially  by  the  system.  It  has  the  title,  “Keyboard”  and  resides  in 
the  “System  Setup”  folder. 


Instance  methods 

The  following  list  shows  all  the  WPKeyboard  methods. 

• “wpAddKeyboardMappingsPage  - WPKeyboard  instance  method”  on  page  9-76 

• “wpAddKeyboardSpecialNeedsPage  - WPKeyboard  instance  method”  on  page  9-77 

• “wpAddKeyboardTimingPage  - WPKeyboard  instance  method”  on  page  9-78 

WPObject  instance  methods 

The  following  list  shows  all  the  methods  overridden  by  the  WPKeyboard  class.  These  methods  are 
overridden  in  order  to  modify  the  behavior  defined  by  an  ancestor  class. 

• “wpAddSettingsPages  - WPObject  instance  method”  on  page  9-89 

• “wpFilterPopupMenu  - WPObject  instance  method”  on  page  9-123 


Class  methods 

The  following  list  shows  all  the  class  methods  overridden  by  the  WPKeyboard  class.  These  methods 
are  overridden  to  modify  the  behavior  defined  by  an  ancestor  class. 

WPObject  class  methods 

• “wpcisQueryDefaultHelp  - WPObject  class  method”  on  page  9-251 

• “wpcisQueryDefauitView  - WPObject  class  method"  on  page  9-252 

• “wpcisQuerylconData  - WPObject  class  method”  on  page  9-261 

• “wpcisQueryStyle  - WPObject  class  method"  on  page  9-267 

• “wpcisQueryTitle  - WPObject  class  method”  on  page  9-268 
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WPMouse 


Class  definition  file:wpmouse.sc 
Class  hierarchy 

SOMObject 
WPObject 
WP  Abstract 

WPMouse 

Description 

This  is  the  mouse  object  class.  An  instance  of  this  class  can  be  created  as  a Workplace  object.  An 
instance  of  this  class  is  created  initially  by  the  system.  It  has  the  title,  “Mouse”  and  resides  in  the 
“System  Setup”  folder. 

Instance  methods 

The  following  table  shows  all  the  WPMouse  methods. 

• “wpAddMouseMappingsPage  - WPMouse  instance  method”  on  page  9-79 

• “wpAddMouseTimingPage  - WPMouse  instance  method”  on  page  9-80 

• “wpAddMouseTypePage  - WPMouse  instance  method”  on  page  9-81 

WPObject  instance  methods 

The  following  list  shows  all  the  methods  overridden  by  the  WPMouse  class.  These  methods  are 
overridden  in  order  to  modify  the  behavior  defined  by  an  ancestor  class. 

• “wpAddSettingsPages  - WPObject  instance  method”  on  page  9-89 

• “wpFilterPopupMenu  - WPObject  instance  method"  on  page  9-123 

Class  methods 

The  following  list  shows  all  the  class  methods  overridden  by  the  WPMouse  class.  These  methods 
are  overridden  to  modify  the  behavior  defined  by  an  ancestor  class. 

WPObject  class  methods 

• “wpcisQueryDefaultHelp  - WPObject  class  method”  on  page  9-251 

• “wpcIsQueryDefauItView  - WPObject  class  method”  on  page  9-252 

• “wpcisQuerylconData  - WPObject  class  method”  on  page  9-261 

• “wpcisQueryStyle  - WPObject  class  method”  on  page  9-267 

• “wpcisQueryTitle  - WPObject  class  method”  on  page  9-268 
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WPObject 


Class  definition  file:wpobject.sc 
Class  hierarchy 

SOMObject 

WPObject 

Description 

This  is  the  root  Workplace  object  class.  This  is  the  fundamental  class  from  which  all  workplace 
objects  are  derived,  irrespective  of  where  they  are  actually  stored.  Immediate  descendant  classes  of 
WPObject  are  called  storage  classes,  since  they  take  responsibility  for  storing  the  object  information, 
typically  in  a persistent  form.  Predefined  workplace  object  storage  classes  are: 

• “WP Abstract”  on  page  9-4 

• “WPFileSystem”  on  page  9-14 

• “WPTransient"  on  page  9-50 

A Workplace  object  of  this  class  cannot  be  created. 


Instance  methods 

The  following  lists  show  how  all  the  WPObject  instance  methods  are  related  within  functional  areas. 

Settings  notebook  methods 

• “wpAddObjectGeneralPage  - WPObject  instance  method”  on  page  9-82 

• “wpAddSettingsPages  - WPObject  instance  method”  on  page  9-89 

• “wpinsertSettingsPage  - WPObject  instance  method”  on  page  9-136 

Save/restore  state  methods 

• “wpRestoreData  - WPObject  instance  method”  on  page  9-192 

• “wpRestoreLong  - WPObject  instance  method”  on  page  9-193 

• “wpRestoreState  - WPObject  instance  method”  on  page  9-194 

• “wpRestoreString  - WPObject  instance  method"  on  page  9-195 

• “wpSaveData  - WPObject  instance  method”  on  page  9-196 

• “wpSavelmmediate  - WPObject  instance  method"  on  page  9-198 

• “wpSaveLong  - WPObject  instance  method”  on  page  9-199 

• “wpSaveState  - WPObject  instance  method”  on  page  9-200 

• “wpSaveString  - WPObject  instance  method"  on  page  9-201 

Object  usage  methods 

• “wpAddToObjUseList  - WPObject  instance  method”  on  page  9-95 

• “wpDeleteFromObjUseList  - WPObject  instance  method”  on  page  9-111 

• “wpFindUseltem  - WPObject  instance  method”  on  page  9-125 

• “wpUnlockObject  - WPObject  instance  method”  on  page  9-237 
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Popup  menu  methods 

• “wpCIose  - WPObject  instance  method"  on  page  9-98 

• “wpCopyObject  - WPObject  instance  method”  on  page  9-105 

• “wpCreateFromTemplate  - WPObject  instance  method”  on  page  9-106 

• “wpCreateShadowObject  - WPObject  instance  method"  on  page  9-107 

• “wpDelete  - WPObject  instance  method"  on  page  9-108 

• “wpDisplayHelp  - WPObject  instance  method"  on  page  9-113 

• “wpFilterPopupMenu  - WPObject  instance  method”  on  page  9-123 

• “wpHide  - WPObject  instance  method”  on  page  9-129 

• “wpInsertPopupMenultems  - WPObject  instance  method”  on  page  9-134 

• “wpMenultemHelpSelected  - WPObject  instance  method”  on  page  9-138 

• “wpMenultemSelected  - WPObject  instance  method”  on  page  9-139 

• “wpModifyPopupMenu  - WPObject  instance  method"  on  page  9-140 

• “wpMoveObject  - WPObject  instance  method”  on  page  9-141 

• “wpOpen  - WPObject  instance  method”  on  page  9-142 

• “wpPrintObject  - WPObject  instance  method”  on  page  9-147 

• “wpRestore  - WPObject  instance  method”  on  page  9-191 

Query  and  Set  object  information  methods 

• “wpQueryConfirmations  - WPObject  instance  method"  on  page  9-157 

• “wpQueryDefaultHelp  - WPObject  instance  method”  on  page  9-159 

• “wpQueryDefauitView  - WPObject  instance  method”  on  page  9-160 

• “wpQueryDetailsData  - WPObject  instance  method"  on  page  9-161 

• “wpQuerylcon  - WPObject  instance  method”  on  page  9-169 

• “wpQuerylconData  - WPObject  instance  method"  on  page  9-170 

• “wpQueryStyle  - WPObject  instance  method”  on  page  9-181 

• “wpQueryTitle  - WPObject  instance  method”  on  page  9-182 

• “wpSetDefaultHelp  - WPObject  instance  method"  on  page  9-209 

• “wpSetDefauItView  - WPObject  instance  method"  on  page  9-211 

• “wpSetlcon  - WPObject  instance  method”  on  page  9-217 

• “wpSetlconData  - WPObject  instance  method”  on  page  9-218 

• “wpSetStyle  - WPObject  instance  method”  on  page  9-226 

• “wpSetTitle  - WPObject  instance  method”  on  page  9-227 

Error  handling  methods 

• “wpQueryError  - WPObject  instance  method”  on  page  9-163 

• “wpSetError  - WPObject  instance  method”  on  page  9-212 

Memory  management  methods 

• “wpAllocMem  - WPObject  instance  method"  on  page  9-97 

• “wpFreeMem  - WPObject  instance  method”  on  page  9-128 

Setup/cleanup  methods 

• “wpFree  - WPObject  instance  method”  on  page  9-127 

• “wpInitData  - WPObject  instance  method”  on  page  9-133 

• “wpScanSetupString  - WPObject  instance  method”  on  page  9-202 

• “wpSetup  - WPObject  instance  method”  on  page  9-229 

• “wpUnlnitData  - WPObject  instance  method”  on  page  9-238 

Direct  manipulation  methods 

• “wpDragOver  - WPObject  instance  method”  on  page  9-118 

• “wpDraggedOverObject  - WPObject  instance  method”  on  page  9-116 

• “wpDrop  - WPObject  instance  method”  on  page  9-119 

• “wpDroppedOnObject  - WPObject  instance  method”  on  page  9-120 

• “wpEndConversation  - WPObject  instance  method"  on  page  9-122 

• “wpFormatDragltem  - WPObject  instance  method”  on  page  9-126 

• “wpRender  - WPObject  instance  method”  on  page  9-189 

• “wpRenderComplete  - WPObject  instance  method"  on  page  9-190 
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Miscellaneous  methods 

• “wpCnrlnsertObject  - WPObject  instance  method”  on  page  9-99 

• “wpCnrRemoveObject  - WPObject  instance  method”  on  page  9-101 

• “wpCnrSetEmphasis  - WPObject  instance  method”  on  page  9-102 

• “wpConfirmDelete  - WPObject  instance  method"  on  page  9-103 

• “wpCopiedFromTemplate  - WPObject  instance  method”  on  page  9-104 

• “wpDoesObjectMatch  - WPObject  instance  method”  on  page  9-114 

• “wpRegisterView  - WPObject  instance  method”  on  page  9-186 

• “wpSwitchTo  - WPObject  instance  method"  on  page  9-236 

SOMObject  methods 

The  following  lists  show  all  the  instance  methods  overridden  by  the  WPObject  class.  These  instance 
methods  are  overridden  in  order  to  modify  the  behavior  defined  by  an  ancestor  class. 

• somFree 

• somlnit 

• somllninit 

Class  Methods 

The  following  list  shows  all  the  WPObject  class  methods. 

• “wpcisCreateDefauItTemplates  - WPObject  class  method”  on  page  9-240 

• “wpcisFindObjectEnd  - WPObject  class  method”  on  page  9-241 

• “wpcisFindObjectFirst  - WPObject  class  method"  on  page  9-242 

• “wpcisFindObjectNext  - WPObject  class  method”  on  page  9-244 

• “wpcisinitData  - WPObject  class  method”  on  page  9-246 

• “wpcIsMakeAwake  - WPObject  class  method”  on  page  9-247 

• “wpcisNew  - WPObject  class  method”  on  page  9-249 

• “wpcisQueryDefaultHelp  - WPObject  class  method”  on  page  9-251 

• “wpcisQueryDefauitView  - WPObject  class  method”  on  page  9-252 

• “wpcIsQueryDetails  - WPObject  class  method"  on  page  9-253 

• “wpcIsQueryDetailsInfo  - WPObject  class  method”  on  page  9-254 

• “wpcIsQueryError  - WPObject  class  method"  on  page  9-258 

• “wpcIsQueryFolder  - WPObject  class  method”  on  page  9-259 

• “wpcIsQuerylcon  - WPObject  class  method”  on  page  9-260 

• “wpcIsQuerylconData  - WPObject  class  method”  on  page  9-261 

• “wpcIsQueryObject  - WPObject  class  method”  on  page  9-264 

• “wpcIsSetError  - WPObject  class  method"  on  page  9-269 

• “wpcIsQuerySettingsPageSize  - WPObject  class  method”  on  page  9-266 

• “wpcIsQueryStyle  - WPObject  class  method”  on  page  9-267 

• “wpcIsQuery Title  - WPObject  class  method”  on  page  9-268 

• “wpcIsUnlnitData  - WPObject  class  method”  on  page  9-270 

SOMObject  methods 

The  following  lists  show  all  the  class  methods  overridden  by  the  WPObject  class.  These  methods  are 
overridden  in  order  to  modify  the  behavior  defined  by  ancestor  class. 

• somllninit 

SOMCIass  methods 

• somlnitClass 

• somNew 

• somRenew 
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WPPalette 


Class  definition  file:wppalet.sc 
Class  hierarchy 

SOMObject 

WPObject 

WPAbstract 

WPPalette 

Description 

This  is  the  palette  object  class.  There  are  no  instances  of  this  class  initially  created  by  the  system. 

Instance  methods 

The  following  list  shows  all  the  WPPalette  instance  methods. 

• “wpDragCell  - WPPalette  instance  method”  on  page  9-115 

• “wpEditCell  - WPPalette  instance  method”  on  page  9-121 

• “wpPaintCell  - WPPalette  instance  method”  on  page  9-143 

• “wpQueryPaletteHelp  - WPPalette  instance  method”  on  page  9-173 

• “wpQueryPalettelnfo  - WPPalette  instance  method”  on  page  9-174 

• “wpRedrawCell  - WPPalette  instance  method”  on  page  9-184 

• “wpSetupCell  - WPPalette  instance  method”  on  page  9-233 

• “wpSetPalettelnfo  - WPPalette  instance  method"  on  page  9-220 

WPObject  instance  methods 

The  following  list  shows  all  the  methods  overridden  by  the  WPPalette  class.  These  methods  are 
overridden  to  modify  the  behavior  defined  by  an  ancestor  class. 

• “wpFilterPopupMenu  - WPObject  instance  method”  on  page  9-123 

• “wpinitData  - WPObject  instance  method"  on  page  9-133 

• “wpMenultemHelpSelected  - WPObject  instance  method”  on  page  9-138 

• “wpMenultemSelected  - WPObject  instance  method”  on  page  9-139 

• “wpModifyPopupMenu  - WPObject  instance  method"  on  page  9-140 

• “wpOpen  - WPObject  instance  method”  on  page  9-142 

• “wpRestoreState  - WPObject  instance  method”  on  page  9-194 

• “wpSaveState  - WPObject  instance  method”  on  page  9-200 

• “wpSetup  - WPObject  instance  method”  on  page  9-229 

• “wpUnlnitData  - WPObject  instance  method"  on  page  9-238 
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wpSetup  override  by  WPPalette 


The  following  are  the  keyname  - value  pairs  added  by  the  WPFontPalette  class. 


KEYNAME 

VALUE 

Description 

XCELLCOUNT 

columns 

Number  of  columns  of  cells. 

YCELLCOUNT 

rows 

Number  of  rows  of  cells. 

XCELLWIDTH 

width 

Width  in  dialog  units  of  each  cell. 

XCELLHEIGHT 

height 

Height  in  dialog  units  of  each  cell. 

XCELLGAP 

gap 

X separation  in  dialog  units  between 
each  cell. 

YCELLGAP 

gap 

Y separation  in  dialog  units  between 
each  cell. 
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Example 

pszSetupString="XCELLC0UNT=3,YCELLC0UNT=4 


Class  methods 

The  following  list  shows  all  the  class  methods  overridden  by  the  WPPalette  class.  These  methods 
are  overridden  to  modify  the  behavior  defined  by  an  ancestor  class. 

WPObject  class  methods 

• “wpcIsQueryDefaultHelp  - WPObject  class  method”  on  page  9-251 

• “wpcIsQueryDefauItView  - WPObject  class  method”  on  page  9-252 

• “wpcIsQueryStyle  - WPObject  class  method”  on  page  9-267 

• “wpcIsQuery Title  - WPObject  class  method”  on  page  9-268 

WPPalette  class  methods 

• “wpcIsQueryEditString  - WPPalette  class  method”  on  page  9-257 
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WPPort 


Class  definition  file:wpport.sc 
Class  hierarchy 

SOMObject 

WPObject 

WPTransient 

WPPort 

Description 

This  is  the  port  object  class.  An  instance  of  this  class  is  created  by  the  print  object  in  its  settings 
view. 

Instance  methods 

The  following  list  shows  all  the  methods  overridden  by  the  WPPort  class.  These  methods  are 
overridden  in  order  to  modify  the  behavior  defined  by  an  ancestor  class. 

WPObject  instance  methods 

• “wpAddSettingsPages  - WPObject  instance  method”  on  page  9-89 

• “wpDragOver  - WPObject  instance  method”  on  page  9-118 

• “wpDrop  - WPObject  instance  method”  on  page  9-119 

• “wpFilterPopupMenu  - WPObject  instance  method”  on  page  9-123 

• “wpinitData  - WPObject  instance  method”  on  page  9-133 

• “wpMenultemHelpSelected  - WPObject  instance  method”  on  page  9-138 

• “wpMenultemSelected  - WPObject  instance  method"  on  page  9-139 

• “wpModifyPopupMenu  - WPObject  instance  method”  on  page  9-140 

• “wpOpen  - WPObject  instance  method”  on  page  9-142 

• “wpSetTitle  - WPObject  instance  method”  on  page  9-227 

• “wpUnlnitData  - WPObject  instance  method”  on  page  9-238 

Class  methods 

The  following  list  shows  all  the  class  methods  overridden  by  the  WPPort  class.  These  methods  are 
overridden  to  modify  the  behavior  defined  by  an  ancestor  class. 

WPObject  class  methods 

• “wpcisQueryDefaultHelp  - WPObject  class  method”  on  page  9-251 

• “wpcisQueryDefauitView  - WPObject  class  method”  on  page  9-252 

• “wpcisQuerylconData  - WPObject  class  method”  on  page  9-261 

• “wpcisQueryStyle  - WPObject  class  method”  on  page  9-267 

• “wpcisQueryTitle  - WPObject  class  method"  on  page  9-268 
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WPPrinter 


Class  definition  file:wpprint.sc 
Class  hierarchy 

SOMObject 

WPObject 

WPAbstract 

WPPrinter 

Description 

This  is  the  print  object  class.  An  instance  of  this  class  can  be  created  as  a Workplace  object.  An 
instance  of  this  class  is  created  initially  by  the  system  in  its  template  form.  It  has  the  title,  “Create 
print  destination”  and  resides  in  the  “Templates”  folder.  Instances  of  this  class  are  also  created 
initially  by  the  system  for  each  print  configured.  Each  instance  will  have  a title  corresponding  to  the 
description  of  the  configured  queue  and  printer  and  will  reside  on  the  desktop. 


Instance  methods 

The  following  list  shows  all  the  WPPrinter  methods. 

• “wpDeleteAllJobs  - WPPrinter  instance  method"  on  page  9-109 

• “wpHoldPrinter  - WPPrinter  instance  method”  on  page  9-132 

• “wpQueryComputerName  - WPPrinter  instance  method"  on  page  9-156 

• “wpQueryPrinterName  - WPPrinter  instance  method”  on  page  9-175 

• “wpReleasePrinter  - WPPrinter  instance  method”  on  page  9-188 

• “wpSetComputerName  - WPPrinter  instance  method”  on  page  9-208 

• “wpSetDefaultPrinter  - WPPrinter  instance  method”  on  page  9-210 

• “wpSetPrinterName  - WPPrinter  instance  method”  on  page  9-221 

WPObject  instance  methods 

The  following  list  shows  all  the  methods  overridden  by  the  WPPrinter  class.  These  methods  are 
overridden  in  order  to  modify  the  behavior  defined  by  an  ancestor  class. 

• “wpAddSettingsPages  - WPObject  instance  method”  on  page  9-89 

• “wpCopiedFromTemplate  - WPObject  instance  method"  on  page  9-104 

• “wpCopyObject  - WPObject  instance  method”  on  page  9-105 

• “wpDragOver  - WPObject  instance  method”  on  page  9-118 

• “wpDrop  - WPObject  instance  method"  on  page  9-119 

• “wpFilterPopupMenu  - WPObject  instance  method"  on  page  9-123 

• “wpFree  - WPObject  instance  method”  on  page  9-127 

• “wpinitData  - WPObject  instance  method”  on  page  9-133 

• “wpMenultemHelpSelected  - WPObject  instance  method”  on  page  9-138 

• “wpMenultemSelected  - WPObject  instance  method"  on  page  9-139 

• “wpModifyPopupMenu  - WPObject  instance  method”  on  page  9-140 

• “wpOpen  - WPObject  instance  method”  on  page  9-142 

• “wpQueryDefaultHelp  - WPObject  instance  method”  on  page  9-159 

• “wpQueryDefauitView  - WPObject  instance  method”  on  page  9-160 

• “wpQuerylcon  - WPObject  instance  method”  on  page  9-169 

• “wpQueryStyle  - WPObject  instance  method"  on  page  9-181 

• “wpQueryTitle  - WPObject  instance  method"  on  page  9-182 

• “wpFtestoreState  - WPObject  instance  method"  on  page  9-194 

• “wpSaveState  - WPObject  instance  method”  on  page  9-200 

• “wpSetTitle  - WPObject  instance  method"  on  page  9-227 

• “wpUnlnitData  - WPObject  instance  method”  on  page  9r238 
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Class  methods 

The  following  list  shows  all  the  class  methods  overridden  by  the  WPPrlnter  class.  These  methods 
are  overridden  to  modify  the  behavior  defined  by  an  ancestor  class. 

WPObject  class  methods 

• “wpcIsQueryDefaultHelp  - WPObject  class  method”  on  page  9-251 

• “wpcIsQueryDefauItView  - WPObject  class  method"  on  page  9-252 

• “wpcIsQuerylconData  - WPObject  class  method”  on  page  9-261 

• “wpcIsQueryStyle  - WPObject  class  method”  on  page  9-267 

• “wpcIsQueryTitle  - WPObject  class  method”  on  page  9-268 
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WPPrinterDriver 


Class  definition  file:wppdr.sc 
Class  hierarchy 

SOMObject 

WPObject 

WPTransient 

WPPrinterDriver 

Description 

This  is  the  printer  driver  object  class.  An  instance  of  this  class  is  created  by  the  print  object  in  its 
settings  view. 


Instance  methods 

The  following  list  shows  all  the  methods  overridden  by  the  WPPrinterDriver  class.  These  methods 
are  overridden  in  order  to  modify  the  behavior  defined  by  an  ancestor  class. 

WPObject  instance  methods 

• “wpDragOver  - WPObject  instance  method”  on  page  9-118 

• “wpDrop  - WPObject  instance  method”  on  page  9-119 

• “wpFilterPopupMenu  - WPObject  instance  method"  on  page  9-123 

• “wpInitData  - WPObject  instance  method”  on  page  9-133 

• “wpMenultemHelpSelected  - WPObject  instance  method”  on  page  9-138 

• “wpMenultemSelected  - WPObject  instance  method”  on  page  9-139 

• “wpModifyPopupMenu  - WPObject  instance  method”  on  page  9-140 

• “wpOpen  - WPObject  instance  method”  on  page  9-142 

• “wpSetTitle  - WPObject  instance  method”  on  page  9-227 

• “wpUnlnitData  - WPObject  instance  method”  on  page  9-238 


Class  methods 

The  following  list  shows  all  the  class  methods  overridden  by  the  WPPrinterDrlve  class.  These 
methods  are  overridden  to  modify  the  behavior  defined  by  an  ancestor  class. 

WPObject  class  methods 

• “wpcisQueryDefaultHelp  - WPObject  class  method”  on  page  9-251 

• “wpcisQueryDefauitView  - WPObject  class  method”  on  page  9-252 

• “wpcisQuerylconData  - WPObject  class  method”  on  page  9-261 

• “wpcIsQueryStyle  - WPObject  class  method”  on  page  9-267 

• “wpcisQueryTitle  - WPObject  class  method”  on  page  9-268 


Chapter  9.  Workplace  Classes,  Instance  Methods,  and  Class  Methods  9-33 


WPProgram 


Class  definition  file:wppgm.sc 
Class  hierarchy 

SOMObject 

WPObject 

WPAbstract 

WPProgram 

Description 

This  is  the  program  object  class.  This  class  provides  an  object  that  points  at  executable  programs, 
and  allows  the  user  to  run  that  program  by  simply  double-clicking  on  the  program  object.  The 
program  can  also  contain  a variety  of  useful  additional  parameters,  such  as  the  environment  for  the 
program  and  the  parameters  that  are  passed  to  it.  An  instance  of  this  class  can  be  created  as  a 
Workplace  object  and  is  created  initially  by  the  system  in  its  template  form.  It  has  the  title 
“Program”  and  resides  in  the  “Templates”  folder. 

Other  instances  of  this  class  initially  created  by  the  system  include: 

• “DOS  Full  Screen"  in  the  “Command  Prompts”  folder 

• “DOS  Window"  in  the  “Command  Prompts”  folder 

• “OS/2  Full  Screen"  in  the  “Command  Prompts"  folder 

• “OS/2  Window”  in  the  “Command  Prompts”  folder 

• Every  object  in  the  “Games”  folder 

• Some  objects  in  the  “Information”  folder 

• Every  object  in  the  “Productivity”  folder 


Instance  methods 

The  following  list  shows  all  the  WPProgram  methods. 

• “wpAddProgramAssociationPage  - WPProgram  instance  method”  on  page  9-84 

• “wpAddProgramPage  - WPProgram  instance  method”  on  page  9-85 

• “wpAddProgramSessionPage  - WPProgram  instance  method”  on  page  9-87 

• “wpQueryAssociationFilter  - WPProgram  instance  method”  on  page  9-152 

• “wpQueryAssociationType  - WPProgram  instance  method”  on  page  9-154 

• “wpQueryProgDetails  - WPProgram  instance  method”  on  page  9-176 

• “wpSetAssociationFilter  - WPProgram  instance  method”  on  page  9-204 

• “wpSetAssociationType  - WPProgram  instance  method”  on  page  9-206 

• “wpSetProgDetails  - WPProgram  instance  method”  on  page  9-222 

WPObject  instance  methods 

The  following  list  shows  all  the  methods  overridden  by  the  WPProgram  class.  These  methods  are 
overridden  in  order  to  modify  the  behavior  defined  by  an  ancestor  class. 

• “wpAddSettingsPages  - WPObject  instance  method”  on  page  9-89 

• “wpCopiedFromTemplate  - WPObject  instance  method”  on  page  9-104 

• “wpCopyObject  - WPObject  instance  method”  on  page  9-105 

• “wpDragOver  - WPObject  instance  method"  on  page  9-118 

• “wpDrop  - WPObject  instance  method”  on  page  9-119 

• “wpMenultemHelpSelected  - WPObject  instance  method”  on  page  9-138 

• “wpMenultemSelected  - WPObject  instance  method”  on  page  9-139 

• “wpModifyPopupMenu  - WPObject  instance  method”  on  page  9-140 

• “wpMoveObject  - WPObject  instance  method"  on  page  9-141 

• “wpOpen  - WPObject  instance  method”  on  page  9-142 

• “wpQueryDefaultHelp  - WPObject  instance  method”  on  page  9-159 

• “wpQuerylcon  - WPObject  instance  method”  on  page  9-169 

• “wpQuerylconData  - WPObject  instance  method"  on  page  9-170 

• “wpRestoreState  - WPObject  instance  method”  on  page  9-194 

• “wpSetTitle  - WPObject  instance  method”  on  page  9-227 
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• “wpSetup  - WPObject  instance  method”  on  page  9-229 

• “wpSaveState  - WPObject  instance  method”  on  page  9-200 

• "wpUnlnitData  - WPObject  instance  method”  on  page  9-238 

wpSetup  override  by  WPProgram 


The  following  table  shows  the  keyname  - value  pairs  added  by  the  WPProgram  class. 


KEYNAME 

VALUE 

Description 

ASSOCFILTER 

filters 

Sets  the  filename  filter  for  files 
associated  to  this  program.  Multiple 
filters  are  separated  by  commas. 

ASSOCTYPE 

type 

Sets  the  type  of  files  associated  to 
this  program.  Multiple  filters  are 
separated  by  commas. 

EXENAME 

filename 

Sets  the  name  of  the  program. 

PARAMETERS 

params 

Sets  the  parameters  list,  which  may 
include  substitution  characters. 

PROGTYPE 

FULLSCREEN 

Sets  the  session  type  to  OS/2  full 
screen 

PM 

Sets  the  session  type  to  PM. 

SEPARATEWIN 

Sets  the  session  type  to  WIN-OS2 
window  running  in  a separate  VDM. 

VDM 

Sets  the  session  type  to  DOS  full 
screen. 

WIN 

Sets  the  session  type  to  WIN-OS2  full 
screen. 

WINDOWABLEVIO 

Sets  the  session  type  to  OS/2 
windowed. 

WINDOWEDVDM 

Sets  the  session  type  to  DOS 
windowed. 

WINDOWEDWIN 

Sets  the  session  type  to  WIN-OS2 
window. 

NOAUTOCLOSE 

YES 

Leaves  the  window  open  upon 
program  termination. 

NO 

Closes  the  window  when  the 
program  terminates. 

STARTUPDIR 

pathname 

Sets  the  working  directory. 

VIEWBUTTON 

not  supported 

This  keyname  is  not  supported  by 
this  class. 

WINDOWPOS 

not  supported 

This  keyname  is  not  supported  by 
this  class. 

pszSetupString="PROGTYPE=VDM;EXENAME=C=\EDIT.EXE; 

ASS0CFILTER=* . DOC , * .TXT ; ASS0CTYPE=P1 ai n Text" 
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Class  methods 

The  following  list  shows  all  the  class  methods  overridden  by  the  WPProgram  class.  These  methods 
are  overridden  to  modify  the  behavior  defined  by  an  ancestor  class. 

WPObject  class  methods 

• “wpcIsQueryDefaultHelp  - WPObject  class  method”  on  page  9-251 

• “wpcIsQueryDefauItView  - WPObject  class  method”  on  page  9-252 

• “wpcIsQuerylconData  - WPObject  class  method"  on  page  9-261 

• “wpcIsQueryTitle  - WPObject  class  method”  on  page  9-268 

• “wpcIsQueryStyle  - WPObject  class  method”  on  page  9-267 
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WPProgramFile 


Class  definition  file:wppgmf.sc 
Class  hierarchy 

SOMObject 

WPObject 

WPFileSystem 

WPProgramFile 

Description 

This  is  the  program  file  object  class.  All  executable  files  are  of  this  class.  From  the  settings 
notebook  pages  for  objects  of  this  class,  it  is  possible  to  set  up  associations  to  various  data  file  types 
(files  with  .TYPE  EAs  or  file  extensions).  It  is  also  possible  to  set  up  a default  working  directory  and 
specify  parameters  to  the  executable  to  be  used  when  it  is  opened  from  the  shell.  An  instance  of  this 
class  can  be  created  as  a Workplace  object.  Instances  of  this  class  are  created  initially  by  the 
system  for  each  program  file  in  the  system.  Each  instance  has  a title  corresponding  to  the  file  name 
of  the  program  file  it  represents  and  resides  in  a folder  corresponding  to  the  physical  directory  in 
which  the  program  file  resides. 


Instance  methods 

The  following  list  shows  all  the  WPProgramFile  methods. 

• “wpAddProgramAssociationPage  - WPProgramFile  instance  method”  on  page  9-83 

• “wpAddProgramPage  - WPProgramFile  instance  method”  on  page  9-86 

• “wpAddProgramSessionPage  - WPProgramFile  instance  method”  on  page  9-88 

• “wpQueryAssociationFilter  - WPProgramFile  instance  method”  on  page  9-153 

• “wpQueryAssociationType  - WPProgramFile  instance  method”  on  page  9-155 

• “wpQueryProgDetails  - WPProgramFile  instance  method”  on  page  9-177 

• “wpSetAssociationFilter  - WPProgramFile  instance  method”  on  page  9-205 

• “wpSetAssociationType  - WPProgramFile  instance  method”  on  page  9-207 

• “wpSetProgDetails  - WPProgramFile  instance  method”  on  page  9-223 

WPObject  instance  methods 

The  following  list  shows  all  the  methods  overridden  by  the  WPProgramFile  class.  These  methods 
are  overridden  in  order  to  modify  the  behavior  defined  by  an  ancestor  class. 

• “wpAddSettingsPages  - WPObject  instance  method”  on  page  9-89 

• “wpCopyObject  - WPObject  instance  method”  on  page  9-105 

• “wpDragOver  - WPObject  instance  method”  on  page  9-118 

• “wpDrop  - WPObject  instance  method”  on  page  9-119 

• “wpMenultemHelpSelected  - WPObject  instance  method”  on  page  9-138 

• “wpMenultemSelected  - WPObject  instance  method”  on  page  9-139 

• “wpModifyPopupMenu  - WPObject  instance  method"  on  page  9-140 

• “wpMoveObject  - WPObject  instance  method”  on  page  9-141 

• “wpOpen  - WPObject  instance  method”  on  page  9-142 

• “wpRestoreState  - WPObject  instance  method”  on  page  9-194 

• “wpSaveState  - WPObject  instance  method”  on  page  9-200 
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wpSetup  override  by  WPProgramFile 


The  following  table  shows  the  keyname-value  pairs  added  by  the  WPProgramFile  class. 


KEYNAME 

VALUE 

Description 

ASSOCFILTER 

filters 

Sets  the  filename  filter  for  files 
associated  to  this  program.  Multiple 
filters  are  separated  by  commas. 

ASSOCTYPE 

type 

Sets  the  type  of  files  associated  to 
this  program.  Multiple  filters  are 
separated  by  commas. 

EXENAME 

filename 

Sets  the  name  of  the  program. 

PARAMETERS 

params 

Sets  the  parameters  list,  which  may 
include  substitution  characters. 

PROGTYPE 

FULLSCREEN 

Sets  the  session  type  to  OS/2  full 
screen 

PM 

Sets  the  session  type  to  PM. 

SEPARATEWIN 

Sets  the  session  type  to  WIN-OS2 
window  running  in  a separate  VDM. 

VDM 

Sets  the  session  type  to  DOS  full 
screen. 

WIN 

Sets  the  session  type  to  WIN-OS2  full 
screen. 

WINDOWABLEVIO 

Sets  the  session  type  to  OS/2 
windowed. 

WINDOWEDVDM 

Sets  the  session  type  to  DOS 
windowed. 

WINDOWEDWIN 

Sets  the  session  type  to  WIN-OS2 
window. 

NOAUTOCLOSE 

YES 

Leaves  the  window  open  upon 
program  termination. 

NO 

Closes  the  window  when  the 
program  terminates. 

STARTUPDIR 

pathname 

Sets  the  working  directory. 

VIEWBUTTON 

not  supported 

This  keyname  is  not  supported  by 
this  class. 

WINDOWPOS 

not  supported 

This  keyname  is  not  supported  by 
this  class. 

pszSetupString="PROGTYPE=VDM;EXENAME=C=\EDIT.EXE; 

ASSOCFILTER=* . DOC , * . TXT ;ASS0CTYPE=P1 ai n Text" 
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Class  methods 

The  following  list  shows  all  the  class  methods  overridden  by  the  WPProgramFile  class.  These 
methods  are  overridden  to  modify  the  behavior  defined  by  an  ancestor  class. 

WPObject  class  methods 

• “wpcIsQueryDefauItView  - WPObject  class  method”  on  page  9-252 

• “wpcIsQuerylconData  - WPObject  class  method”  on  page  9-261 

• “wpcIsQueryStyle  - WPObject  class  method”  on  page  9-267 

• “wpcIsQueryTitle  - WPObject  class  method”  on  page  9-268 
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WPSchemePalette 


Class  definition  fiie:wpscheme.sc 
Class  hierarchy 

SOMObject 

WPObject 

WPAbstract 

WPPalette 

WPSchemePalette 


Description 

This  is  the  scheme  palette  object  class.  An  instance  of  this  class  can  be  created  as  a Workplace 
object.  An  instance  of  this  class  is  created  initially  by  the  system.  It  has  the  title,  “Window 
Schemes”  and  resides  in  the  “System  Setup"  folder.  There  are  currently  no  methods  defined  for  the 
WPSchemePalette  workplace  object  class. 


Instance  methods 

The  following  list  shows  all  the  methods  overridden  by  the  WPSchemePalette  class.  These  methods 
are  overridden  in  order  to  modify  the  behavior  defined  by  an  ancestor  class. 

WPObject  instance  methods 

• “wpMenultemHelpSelected  - WPObject  instance  method”  on  page  9-138 

• “wpSetup  - WPObject  instance  method”  on  page  9-229 

WPPalette  methods 

• “wpDragCell  - WPPalette  instance  method”  on  page  9-115 

• “wpEditCell  - WPPalette  instance  method”  on  page  9-121 

• “wpPaintCell  - WPPalette  instance  method"  on  page  9-143 

• “wpQueryPaletteHelp  - WPPalette  instance  method”  on  page  9-173 

• “wpSetupCell  - WPPalette  instance  method”  on  page  9-233 


Class  methods 

The  following  list  shows  all  the  class  methods  overridden  by  the  WPSchemePalette  class.  These 
methods  are  overridden  to  modify  the  behavior  defined  by  an  ancestor  class. 

WPObject  class  methods 

• “wpcisQueryDefaultHelp  - WPObject  class  method”  on  page  9-251 

• “wpcIsQueryTitle  - WPObject  class  method"  on  page  9-268 

WPPalette  class  methods 

• “wpcIsQueryEditString  - WPPalette  class  method"  on  page  9-257 

• “wpcIsQuerylconData  - WPObject  class  method”  on  page  9-261 

• “wpcIsQueryStyle  - WPObject  class  method”  on  page  9-267 
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WPShadow 


Class  definition  file:wpshadow.sc 
Class  hierarchy 

SOMObject 

WPObject 

WPAbstract 

WPShadow 

Description 

This  is  the  shadow  object  class.  This  class  provides  a persistent  link  or  reference  to  any  other  object 
class.  This  is  achieved  by  storing  away  the  location  and  identity  of  the  object  that  it  is  linked  to  and 
then  rerouting  all  requests  for  help,  context  menus,  and  open  views  on  to  the  object  that  it  is  linked 
to.  Delete,  Copy,  and  Move  are  the  only  action  requests  that  are  handled  by  the  WPShadow  object 
and  are  not  rerouted  to  the  linked  object.  An  instance  of  this  class  can  be  created  as  a Workplace 
object.  There  are  no  instances  of  this  class  initially  created  by  the  system. 


Instance  methods 

The  following  list  shows  all  the  WPShadow  methods. 

• “wpQueryShadowedObject  - WPShadow  instance  method”  on  page  9-180 

• “wpSetShadowTitle  - WPShadow  instance  method”  on  page  9-225 

WPObject  instance  methods 

The  following  list  shows  all  the  methods  overridden  by  the  WPShadow  class.  These  methods  are 
overridden  in  order  to  modify  the  behavior  defined  by  an  ancestor  class. 

• “wpConfirmDelete  - WPObject  instance  method”  on  page  9-103 

• “wpDragOver  - WPObject  instance  method”  on  page  9-118 

• “wpDraggedOverObject  - WPObject  instance  method”  on  page  9-116 

• “wpDrop  - WPObject  instance  method”  on  page  9-119 

• “wpDroppedOnObject  - WPObject  instance  method”  on  page  9-120 

• “wpFilterPopupMenu  - WPObject  instance  method”  on  page  9-123 

• “wpFormatDragltem  - WPObject  instance  method”  on  page  9-126 

• “wpinitData  - WPObject  instance  method”  on  page  9-133 

• “wpinsertPopupMenultems  - WPObject  instance  method”  on  page  9-134 

• “wpMenultemSelected  - WPObject  instance  method”  on  page  9-139 

• “wpModifyPopupMenu  - WPObject  instance  method”  on  page  9-140 

• “wpOpen  - WPObject  instance  method”  on  page  9-142 

• “wpPrintObject  - WPObject  instance  method”  on  page  9-147 

• “wpQueryDefaultHelp  - WPObject  instance  method”  on  page  9-159 

• “wpQueryStyle  - WPObject  instance  method”  on  page  9-181 

• “wpRestoreState  - WPObject  instance  method”  on  page  9-194 

• “wpSaveState  - WPObject  instance  method"  on  page  9-200 

• “wpSetTitle  - WPObject  instance  method”  on  page  9-227 

• “wpUnlnitData  - WPObject  instance  method”  on  page  9-238 

These  are  the  keyname-value  pairs  supported  by  the  WPObject  class. 


KEYNAME 

VALUE 

Description 

SHADOWID 

<name>  or 
filename 

This  specifies  the  object  for  which 
this  object  is  a shadow  of.  The  value 
for  this  keyname  is  an  object's  id 
(OBJECTID)  or  a fully  qualified 
pathname  of  a directory,  program 
file,  or  data  file. 
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Class  methods 

The  following  list  shows  all  the  class  methods  overridden  by  the  WPShadow  class.  These  methods 
are  overridden  to  modify  the  behavior  defined  by  an  ancestor  class. 

WPObject  class  methods 

• “wpcIsQuerylconData  - WPObject  class  method”  on  page  9-261 

• “wpcIsQueryStyle  - WPObject  class  method”  on  page  9-267 

• “wpcIsQueryTitle  - WPObject  class  method”  on  page  9-268 
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WPShredder 


Class  definition  file:wpshred.sc 
Class  hierarchy 

SOMObject 

WPObject 

WPAbstract 

WPShredder 

Description 

This  is  the  shredder  device  object  class.  An  instance  of  this  class  can  be  created  as  a Workplace 
object.  An  instance  of  this  class  is  created  initially  by  the  system.  It  has  the  title  “shredder”  and 
resides  on  the  desktop.  There  are  currently  no  methods  defined  for  the  WPShredder  Workplace 
object  class. 

Instance  methods 

The  following  list  shows  all  the  methods  overridden  by  the  WPShredder  class.  These  methods  are 
overridden  in  order  to  modify  the  behavior  defined  by  an  ancestor  class. 

WPObject  instance  methods 

• “wpDragOver  - WPObject  instance  method”  on  page  9-118 

• “wpDrop  - WPObject  instance  method”  on  page  9-119 

• “wpFilterPopupMenu  - WPObject  instance  method"  on  page  9-123 

• “wpModifyPopupMenu  - WPObject  instance  method”  on  page  9-140 

• “wpOpen  - WPObject  instance  method”  on  page  9-142 

Class  methods 

The  following  list  shows  all  the  class  methods  overridden  by  the  WPShredder  class.  These  methods 
are  overridden  to  modify  the  behavior  defined  by  an  ancestor  class. 

WPObject  class  methods 

• “wpcisQueryDefaultHelp  - WPObject  class  method”  on  page  9-251 

• “wpcisQuerylconData  - WPObject  class  method"  on  page  9-261 

• “wpcisQueryStyle  - WPObject  class  method”  on  page  9-267 

• “wpcisQueryTitle  - WPObject  class  method”  on  page  9-268 
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WPSound 


Class  definition  file:wpsound.sc 
Class  hierarchy 

SOMObject 

WPObject 

WPAbstract 

WPSound 

Description 

This  is  the  sound  object  class.  An  instance  of  this  class  can  be  created  as  a Workplace  object.  An 
instance  of  this  class  is  created  initially  by  the  system.  It  has  the  title  “Sound”  and  resides  in  the 
“System  Setup”  folder. 

Instance  methods 

The  following  list  shows  all  the  WPSound  methods. 

• “wpAddSoundWarningBeepPage  - WPSound  instance  method”  on  page  9-90 

WPObject  instance  methods 

The  following  list  shows  all  the  methods  overridden  by  the  WPSound  class.  These  methods  are 
overridden  in  order  to  modify  the  behavior  defined  by  an  ancestor  class. 

• “wpAddSettingsPages  - WPObject  instance  method"  on  page  9-89 

• “wpFilterPopupMenu  - WPObject  instance  method”  on  page  9-123 

Class  methods 

The  following  list  shows  all  the  class  methods  overridden  by  the  WPSound  class.  These  methods  are 
overridden  to  modify  the  behavior  defined  by  an  ancestor  class. 

WPObject  class  methods 

• “wpcIsQueryDefaultHelp  - WPObject  class  method”  on  page  9-251 

• “wpcisQueryDefauItView  - WPObject  class  method”  on  page  9-252 

• “wpcisQuerylconData  - WPObject  class  method”  on  page  9-261 

• “wpcIsQueryStyle  - WPObject  class  method”  on  page  9-267 

• “wpcIsQueryTitle  - WPObject  class  method"  on  page  9-268 
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WPSpecialNeeds 


Class  definition  file:wpspneed.sc 
Class  hierarchy 

SOMObject 
WPObject 
WP  Abstract 

WPSpecialNeeds 

Description 

This  is  the  special  needs  object  class.  An  instance  of  this  class  can  be  created  as  a Workplace 
object.  An  instance  of  this  class  is  created  initially  by  the  system  when  the  keyboard  special  needs 
mode  is  activated  via  the  keyboard  object  settings.  It  has  the  title,  “Special  Needs”  and  resides  on 
the  desktop. 


Instance  methods 

There  are  currently  no  methods  defined  for  the  WPSpecialNeeds  Workplace  object  class. 

WPObject  instance  methods 

The  following  list  shows  all  the  methods  overridden  by  the  WPSpecialNeeds  class.  These  methods 
are  overridden  in  order  to  modify  the  behavior  defined  by  an  ancestor  class. 

• “wpFilterPopupMenu  - WPObject  instance  method”  on  page  9-123 


Class  methods 

The  following  list  shows  all  the  class  methods  overridden  by  the  WPSpecialNeeds  class.  These 
methods  are  overridden  to  modify  the  behavior  defined  by  an  ancestor  class. 

WPObject  class  methods 

• “wpcisQueryDefaultHelp  - WPObject  class  method”  on  page  9-251 

• “wpcisQueryDefauItView  - WPObject  class  method”  on  page  9-252 

• “wpcisQuerylconData  - WPObject  class  method”  on  page  9-261 

• “wpcisQueryTitle  - WPObject  class  method”  on  page  9-268 
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WPSpooler 


Class  definition  file: wpspool.se 
Class  hierarchy 

SOMObject 

WPObject 

WPAbstract 

WPSpooler 


Description 

This  is  the  spooler  object  class.  An  instance  of  this  class  is  created  initially  by  the  system.  It  has  the 
title,  “Spooler”  and  resides  in  the  “System  Configuration”  folder. 


Instance  methods 

The  following  list  shows  all  the  methods  overridden  by  the  WPSpooler  class.  These  methods  are 
overridden  in  order  to  modify  the  behavior  defjned  by  an  ancestor  class. 

WPObject  instance  methods 

• “wpAddSettingsPages  - WPObject  instance  method”  on  page  9-89 

• “wpDragOver  - WPObject  instance  method”  on  page  9-118 

• “wpDrop  - WPObject  instance  method”  on  page  9-119 

• “wpFilterPopupMenu  - WPObject  instance  method”  on  page  9-123 

• “wpinitData  - WPObject  instance  method”  on  page  9-133 

• “wpMenultemHelpSelected  - WPObject  instance  method"  on  page  9-138 

• “wpMenultemSelected  - WPObject  instance  method”  on  page  9-139 

• “wpModifyPopupMenu  - WPObject  instance  method”  on  page  9-140 

• “wpOpen  - WPObject  instance  method”  on  page  9-142 

• “wpRestoreState  - WPObject  instance  method"  on  page  9-194 

• “wpSaveState  - WPObject  instance  method”  on  page  9-200 

• “wpSetTitle  - WPObject  instance  method”  on  page  9-227 

• “wpUnlnitData  - WPObject  instance  method”  on  page  9-238 


Class  methods 

The  following  list  shows  all  the  class  methods  overridden  by  the  WPSpooler  class.  These  methods 
are  overridden  to  modify  the  behavior  defined  by  an  ancestor  class. 

WPObject  class  methods 

• “wpcisQueryDefaultHelp  - WPObject  class  method"  on  page  9-251 

• “wpcisQueryDefauItView  - WPObject  class  method”  on  page  9-252 

• “wpcisQuerylconData  - WPObject  class  method”  on  page  9-261 

• “wpcisQueryStyle  - WPObject  class  method”  on  page  9-267 

• “wpcisQueryTitle  - WPObject  class  method”  on  page  9-268 
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WPStartup 


Class  definition  file:wpstart.sc 
Class  hierarchy 

SOMObject 

WPObject 

WPFileSystem 

WPFolder 

WPStartup 

Description 

This  is  the  startup  folder  object  class.  Any  object  in  the  startup  folder  will  be  automatically  opened 
every  time  the  system  is  restarted.  Any  object  in  the  system  that  is  open  at  shutdown  time  will  be 
automatically  reopened  when  the  system  is  restarted.  The  startup  folder  is  used  to  automatically 
open  (start)  objects  that  are  not  necessarily  open  (running)  when  the  system  is  shutdown.  This 
usually  includes  things  such  as  a batch  file  that  initializes  the  network  and  then  terminates.  An 
instance  of  this  class  can  be  created  as  a Workplace  object  and  is  created  initially  by  the  system.  It 
has  the  title  “Startup”  and  resides  in  the  “OS/2  System”  folder. 

Instance  methods 

There  are  currently  no  methods  defined  for  the  WPStartup  Workplace  object  class. 

WPObject  instance  methods 

The  following  list  shows  all  the  methods  overridden  by  the  WPStartup  class.  These  methods  are 
overridden  in  order  to  modify  the  behavior  defined  by  an  ancestor  class. 

• “wpFree  - WPObject  instance  method”  on  page  9-127 

• “wpSetup  - WPObject  instance  method”  on  page  9-229 

Class  methods 

The  following  list  shows  all  the  class  methods  overridden  by  the  WPStartup  class.  These  methods 
are  overridden  to  modify  the  behavior  defined  by  an  ancestor  class. 

WPObject  class  methods 

• “wpcisQueryDefaultHelp  - WPObject  class  method”  on  page  9-251 

• "wpcisQuerylconData  - WPObject  class  method”  on  page  9-261 

• “wpcIsQueryStyle  - WPObject  class  method”  on  page  9-267 

• “wpcIsQueryTitle  - WPObject  class  method”  on  page  9-268 
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WPSystem 


Class  definition  file:wpsystem.sc 
Class  hierarchy 

SOMObject 

WPObject 

WPAbstract 

WPSyslem 

Description 

This  is  the  system  object  class.  An  instance  of  this  class  can  be  created  as  a Workplace  object  and 
is  created  initially  by  the  system.  It  has  the  title,  “System”  and  resides  in  the  “System  Setup”  folder. 


Instance  methods 

The  following  list  shows  all  the  WPSystem  class  methods. 

• “wpAddSystemConfirmationPage  - WPSystem  instance  method”  on  page  9-91 

• “wpAddSystemLogoPage  - WPSystem  instance  method”  on  page  9-92 

• “wpAddSystemPrintScreenPage  - WPSystem  instance  method”  on  page  9-93 

• “wpAddSystemWindowPage  - WPSystem  instance  method”  on  page  9-94 

WPObject  instance  methods 

The  following  list  shows  all  the  methods  overridden  by  the  WPSystem  class.  These  methods  are 
overridden  in  order  to  modify  the  behavior  defined  by  an  ancestor  class. 

• “wpAddSettingsPages  - WPObject  instance  method"  on  page  9-89 

• “wpFilterPopupMenu  - WPObject  instance  method"  on  page  9-123 

• “wpRestoreState  - WPObject  instance  method”  on  page  9-194 

• “wpSaveState  - WPObject  instance  method”  on  page  9-200 

Class  methods 

The  following  list  shows  all  the  class  methods  overridden  by  the  WPSystem  class.  These  methods 
are  overridden  to  modify  the  behavior  defined  by  an  ancestor  class. 

WPObject  class  methods 

• “wpcisQueryDefaultHelp  - WPObject  class  method”  on  page  9-251 

• “wpcIsQueryDefauItView  - WPObject  class  method”  on  page  9-252 

• “wpcisQuerylconData  - WPObject  class  method”  on  page  9-261 

• “wpcisQueryStyle  - WPObject  class  method"  on  page  9-267 

• “wpcisQueryTitle  - WPObject  class  method”  on  page  9-268 
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WPTemplateFolder 


Class  definition  file:wptplfdr.sc 
Class  hierarchy 

SOMObject 

WPObject 

WPFileSystem 

WPFolder 

WPT  emplateFolder 

Description 

This  is  the  template  folder  object  class.  This  class  of  folder  is  guaranteed  to  always  contain  a 
template  instance  of  every  class  of  object  that  the  user  can  create  that  supports  the  “Create  another” 
action. 

A WPTemplateFolder  object  is  a normal  folder  in  all  respects  other  than: 

• It  always  contains  a template  for  every  class  that  supports  them. 

• The  last  template  for  each  object  class  can  not  be  deleted  from  the  folder. 

An  instance  of  this  class  can  be  created  as  a Workplace  object  and  is  created  initially  by  the  system. 
It  has  the  title,  “Templates”  and  resides  on  the  desktop.  A template  instance  is  also  created  for  each 
data  type  defined  in  an  application's  ASSOCTABLE  resource. 

Instance  methods 

There  are  currently  no  methods  defined  for  the  WPTemplateFolder  Workplace  object  class. 

WPObject  instance  methods 

The  following  list  shows  all  the  methods  overridden  by  the  WPTemplateFolder  class.  These  methods 
are  overridden  in  order  to  modify  the  behavior  defined  by  an  ancestor  class. 

• “wpPopulate  - WPFolder  instance  method”  on  page  9-144 

Class  methods 

The  following  shows  the  class  methods  overridden  by  the  WPTemplateFolder  class.  These  methods 
are  overridden  to  modify  the  behavior  defined  by  an  ancestor  class. 

WPObject  class  methods 

• “wpcIsQuerylconData  - WPObject  class  method"  on  page  9-261 

• “wpcisQueryStyle  - WPObject  class  method”  on  page  9-267 

• “wpcIsQuery Title  - WPObject  class  method”  on  page  9-268 
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WPTransient 


Class  definition  file:wptrans.sc 
Class  hierarchy 

SOMObject 

WPObject 

WPTransient 

Description 

This  is  the  non-persistent  object  storage  class.  The  WPTransient  class  is  a storage  class  with  no 
storage  medium.  That  means  that  instances  of  object  classes  derived  from  WPTransient  do  not 
persist  across  reboots.  This  class  is  available  for  applications  which  need  to  utilize  a large  amount  of 
workplace  functionality  (such  as  context  menus  and  settings  notebooks)  in  their  object  class  without 
having  to  be  a file,  directory  or  a record  in  the  INI  file.  An  instance  of  this  class  can  be  created  as  a 
Workplace  object.  There  are  no  instances  of  this  class  initially  created  by  the  system. 

Instance  methods 

There  are  currently  no  methods  defined  for  the  WPTransient  Workplace  object  class. 

WPObject  instance  methods 

The  following  list  shows  all  the  methods  overridden  by  the  WPTransient  class.  These  methods  are 
overridden  in  order  to  modify  the  behavior  defined  by  an  ancestor  class. 

• “wpCopyObject  - WPObject  instance  method”  on  page  9-105 

Class  methods 

The  following  list  shows  all  the  class  methods  overridden  by  the  WPTransient  class.  These  methods 
are  overridden  to  modify  the  behavior  defined  by  an  ancestor  class. 

WPObject  class  methods 

• “wpcisQuerylconData  - WPObject  class  method"  on  page  9-261 

• “wpcisQueryStyle  - WPObject  class  method”  on  page  9-267 

• “wpcisQueryTitle  - WPObject  class  method”  on  page  9-268 
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WPQueueDriver 


Class  definition  file:wpqdr.sc 
Class  hierarchy 

SOMObject 

WPObject 

WPTransient 

WPQueueDriver 

Description 

This  is  the  queue  driver  object  class.  An  instance  of  this  class  is  created  by  the  print  object  in  its 
settings  view. 

Instance  methods 

The  following  list  shows  all  the  methods  overridden  by  the  WPQueueDriver  class.  These  methods 
are  overridden  in  order  to  modify  the  behavior  defined  by  an  ancestor  class. 

WPObject  instance  methods 

• “wpDragOver  - WPObject  instance  method”  on  page  9-118 

• “wpDrop  - WPObject  instance  method”  on  page  9-119 

• “wpFilterPopupMenu  - WPObject  instance  method”  on  page  9-123 

• “wpinitData  - WPObject  instance  method"  on  page  9-133 

• “wpMenultemHelpSelected  - WPObject  instance  method”  on  page  9-138 

• “wpMenultemSelected  - WPObject  instance  method”  on  page  9-139 

• “wpModifyPopupMenu  - WPObject  instance  method”  on  page  9-140 

• “wpOpen  - WPObject  instance  method”  on  page  9-142 

• “wpSetTitle  - WPObject  instance  method”  on  page  9-227 

• “wpUnlnitData  - WPObject  instance  method”  on  page  9-238 

Class  methods 

The  following  list  shows  all  the  class  methods  overridden  by  the  WPQueueDriver  class.  These 
methods  are  overridden  to  modify  the  behavior  defined  by  an  ancestor  class. 

WPObject  class  methods 

• “wpcisQueryDefaultHelp  - WPObject  class  method"  on  page  9-251 

• “wpcisQueryDefauitView  - WPObject  class  method”  on  page  9-252 

• “wpcisQuerylconData  - WPObject  class  method”  on  page  9-261 

• “wpcisQueryStyle  - WPObject  class  method”  on  page  9-267 

• “wpcisQuery Title  - WPObject  class  method”  on  page  9-268 
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Workplace  Instance  Methods 

The  following  pages  contain  an  alphabetical  listing  of  the  Workplace  Instance  methods. 
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wpAddClockAlarmPage  - 
WPCIock  instance  method 


#define  INCL_WINWORKPLACE 


ULONG  wpAddClockAlarmPage  (WPCiock  * sell,  HWND  hwndNotebook) 


The  wpAddClockAlarmPage  instance  method  is  called  to  allow  the  object  to  add  the  Alarm  page  to  its 
settings  notebook. 

Parameters 

self  (WPCiock  *)  - input 
The  pointer  to  this  object. 
hwndNotebook  (HWND)  - input 
The  settings  notebook  handle. 


Returns 

Page  identifier: 

0 Error  occurred. 

Pageld  Identifier  for  the  inserted  page. 

Usage 

This  method  must  only  be  called  from  within  an  override  of  the  wpAddSettingsPages  method. 

How  to  Override 

This  method  should  always  be  overridden  in  order  to  replace  or  remove  the  Alarm  page  from  the 
object's  settings  notebook. 

To  remove  the  page  from  the  settings  notebook,  the  override  method  should  return 
SETTINGS_PAGE_REMOVED  without  calling  the  parent  method.  To  replace  the  page  with  another 
page,  the  override  method  should  call  the  wpInsertSettingsPage  method  without  calling  the  parent 
method. 

Related  Methods 

See  Notebook  Control  Window  Messages  for  related  messages. 

• wpAddSettingsPages 

• wpInsertSettingsPage 
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wpAddClockDateTimePage 
WPCIock  instance  method 


#define  INCL_WINWORKPLACE 


ULONG  wpAddClockDateTimePage  (WPCIock  * self,  HWND  hwndNotebook) 


The  wpAddClockDateTimePage  instance  method  is  called  to  allow  the  object  to  add  the  Date/Time 
page  to  its  settings  notebook. 

Parameters 

self  (WPCIock  *)  - input 
The  pointer  to  this  object. 
hwndNotebook  (HWND)  - input 
The  settings  notebook  handle. 


Returns 

Page  identifier: 

0 Error  occurred. 

Pageld  Identifier  for  the  inserted  page. 

Usage 

This  method  must  only  be  called  from  within  an  override  of  the  wpAddSettingsPages  method. 


How  to  Override 

This  method  should  always  be  overridden  in  order  to  replace  or  remove  the  Date/Time  page  from  the 
object's  settings  notebook.  To  remove  the  page  from  the  settings  notebook,  the  override  method 
should  return  SETTINGS_PAGE_REMOVED  without  calling  the  parent  method.  To  replace  the  page 
with  another  page,  the  override  method  should  call  the  wpinsertSettingsPage  method  without  calling 
the  parent  method. 


Related  Methods 

See  Notebook  Control  Window  Messages  for  related  messages. 


• wpAddSettingsPages 

• wpinsertSettingsPage 
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wpAddClockViewIPage  - 
WPCIock  instance  method 


#define  INCL_WINWORKPLACE 


ULONG  wp AddCiockVIewl  Page  (WPCIock  * self,  HWND  hwndNotebook) 


The  wpAddClockViewIPage  instance  method  is  called  to  allow  the  object  to  add  the  View  1 page  to 
Its  settings  notebook. 


Parameters 

self  (WPCIock  *)  - input 
The  pointer  to  this  object. 
hwndNotebook  (HWND)  - input 
The  settings  notebook  handle. 


Returns 

Page  identifier: 

0 Error  occurred. 

Pageld  Identifier  for  the  inserted  page. 

Usage 

This  method  must  only  be  called  from  within  an  override  of  the  wpAddSettingsPages  method. 


How  to  Override 

This  method  should  always  be  overridden  in  order  to  replace  or  remove  the  View  1 page  from  the 
object's  settings  notebook.  To  remove  the  page  from  the  settings  notebook,  the  override  method 
should  return  SETTINGS_PAGE_REMOVED  without  calling  the  parent  method.  To  replace  the  page 
with  another  page,  the  override  method  should  calf  the  wpinsertSettingsPage  method  without  calling 
the  parent  method. 


Related  Methods 

See  Notebook  Control  Window  Messages  for  related  messages. 


• wpAddSettingsPages 

• wpinsertSettingsPage 
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wpAddClockView2Page  - 
WPCIock  instance  method 


#define  INCL_WINWORKPLACE 


ULONG  wpAddClockVlew2Page  (WPCIock  * self,  HWND  hwndNotebook) 


The  wpAddClockView2Page  instance  method  is  called  to  allow  the  object  to  add  the  View  2 page  to 
its  settings  notebook. 


Parameters 

self  (WPCIock  *)  - input 
The  pointer  to  this  object. 
hwndNotebook  (HWND)  - input 
The  settings  notebook  handle. 


Returns 

Page  identifier: 

0 Error  occurred. 

Pageld  Identifier  for  the  inserted  page. 

Usage 

This  method  must  only  be  called  from  within  an  override  of  the  wpAddSettingsPages  method. 


How  to  Override 

This  method  should  always  be  overridden  in  order  to  replace  or  remove  the  View  2 page  from  the 
object's  settings  notebook.  To  remove  the  page  from  the  settings  notebook,  the  override  method 
should  return  SETTINGS_PAGE_REMOVED  without  calling  the  parent  method.  To  replace  the  page 
with  another  page,  the  override  method  should  call  the  wpinsertSettingsPage  method  without  calling 
the  parent  method. 


Related  Methods 

See  Notebook  Control  Window  Messages  for  related  messages. 


• wpAddSettingsPages 

• wpinsertSettingsPage 
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wpAddCountryDatePage  - 
WPCountry  instance  method 


#define  INCL_WINWORKPLACE 


ULONG  wpAddCountryDatePage  (WPCountry  * self,  HWND  hwndNotebook) 


The  wpAddCountryDatePage  instance  method  is  called  to  allow  the  object  to  add  the  Date  page  to  its 
settings  notebook. 


Parameters 

self  (WPCountry  *)  - input 
The  pointer  to  this  object. 
hwndNotebook  (HWND)  - input 
The  settings  notebook  handle. 


Returns 

Page  identifier: 

0 Error  occurred. 

Pageld  Identifier  for  the  inserted  page. 

Usage 

This  method  must  only  be  called  from  within  an  override  of  the  wpAddSettingsPages  method. 


How  to  Override 

This  method  should  always  be  overridden  in  order  to  replace  or  remove  the  Date  page  from  the 
object's  settings  notebook.  To  remove  the  page  from  the  settings  notebook,  the  override  method 
should  return  SETTINGS_PAGE_REMOVED  without  calling  the  parent  method.  To  replace  the  page 
with  another  page,  the  override  method  should  call  the  wpInsertSettingsPage  method  without  calling 
the  parent  method. 


Related  Methods 

See  Notebook  Control  Window  Messages  for  related  messages. 


• wpAddSettingsPages 

• wpInsertSettingsPage 
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wpAddCountryNumbersPage 
WPCountry  instance  method 


#define  INCL_WINWORKPLACE 


ULONG  wpAddCountryNumbersPage  (WPCountry  * self,  HWND  hwndNotebook) 


The  wpAddCountryNumbersPage  instance  method  is  called  to  allow  the  object  to  add  the  Numbers 
page  to  its  settings  notebook. 

Parameters 

self  (WPCountry  *)  — input 
The  pointer  to  this  object. 
hwndNotebook  (HWND)  - input 
The  settings  notebook  handle. 


Returns 

Page  identifier: 

0 Error  occurred. 

Pageld  Identifier  for  the  inserted  page. 

Usage 

This  method  must  only  be  called  from  within  an  override  of  the  wpAddSettingsPages  method. 


How  to  Override 

This  method  should  always  be  overridden  in  order  to  replace  or  remove  the  Numbers  page  from  the 
object's  settings  notebook.  To  remove  the  page  from  the  settings  notebook,  the  override  method 
should  return  SETTlNGS_PAGE_REMOVED  without  calling  the  parent  method.  To  replace  the  page 
with  another  page,  the  override  method  should  call  the  wpInsertSettingsPage  method  without  calling 
the  parent  method. 


Related  Methods 

See  Notebook  Control  Window  Messages  for  related  messages. 


• wpAddSettingsPages 

• wpInsertSettingsPage 
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wpAddCountryPage  - 
WPCountry  instance  method 


#define  INCL_WINWORKPLACE 


ULONG  wpAddCountryPage  (WPCountry  * self,  HWND  hwndNotebook) 


The  wpAddCountryPage  instance  method  is  called  to  allow  the  object  to  add  the  Country  page  to  its 
settings  notebook. 

Parameters 

self  (WPCountry  *)  - input 
The  pointer  to  this  object. 
hwndNotebook  (HWND)  - input 
The  settings  notebook  handle. 


Returns 

Page  identifier: 

0 Error  occurred. 

Pageld  Identifier  for  the  inserted  page. 

Usage 

This  method  must  only  be  called  from  within  an  override  of  the  wpAddSettingsPages  method. 

How  to  Override 

This  method  should  always  be  overridden  in  order  to  replace  or  remove  the  Country  page  from  the 
object's  settings  notebook.  To  remove  the  page  from  the  settings  notebook,  the  override  method 
should  return  SETTINGS_PAGE_REMOVED  without  calling  the  parent  method.  To  replace  the  page 
with  another  page,  the  override  method  should  call  the  wpinsertSettingsPage  method  without  calling 
the  parent  method. 


Related  Methods 

See  Notebook  Control  Window  Messages  for  related  messages. 


• wpAddSettingsPages 

• wpinsertSettingsPage 
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wpAddCountryTimePage  - 
WPCountry  instance  method 


#define  INCL_WINWORKPLACE 


ULONG  wpAddCountryTimePage  (WPCountry  * self,  HWND  hwndNotebook) 


The  wpAddCountryTimePage  instance  method  is  called  to  allow  the  object  to  add  the  Time  page  to 
its  settings  notebook. 

Parameters 

self  (WPCountry  *)  - input 
The  pointer  to  this  object. 
hwndNotebook  (HWND)  - input 
Settings  notebook  handle. 

Returns 

Page  identifier: 

0 Error  occurred. 

Pageld  Identifier  for  the  inserted  page. 


Usage 

This  method  must  only  be  called  from  within  an  override  of  the  wpAddSettingsPages  method. 


How  to  Override 

This  method  should  always  be  overridden  in  order  to  replace  or  remove  the  Time  page  from  the 
object's  settings  notebook. 

To  remove  the  page  from  the  settings  notebook,  the  override  method  should  return 
SETTINGS _P AGE _REMOV ED  without  calling  the  parent  method.  To  replace  the  page  with  another 
page,  the  override  method  should  call  the  wpinsertSettingsPage  method  without  calling  the  parent 
method. 

Related  Methods 

See  Notebook  Control  Window  Messages  for  related  messages. 

• wpAddSettingsPages 

• wpinsertSettingsPage 


9-60  PM  Programming  Reference 


wpAddDesktopLockupIPage  - 
WPDesktop  instance  method 


#define  INCL_WINWORKPLACE 


ULONG  wpAddDesktopLockupIPage  (WPDesktop  * self,  HWND  hwndNotebook) 


The  wpAddDesktopLockupl  Page  instance  method  is  called  to  allow  the  object  to  add  the  Lockup  1 
page  to  its  settings  notebook. 


Parameters 

self  (WPDesktop  *)  - input 
The  pointer  to  this  object. 
hwndNotebook  (HWND)  - input 
Settings  notebook  handle. 


Returns 

Page  identifier: 

0 Error  occurred. 

Pageld  Identifier  for  the  inserted  page. 

Usage 

This  method  must  only  be  called  from  within  an  override  of  the  wpAddSettingsPages  method. 


How  to  Override 

This  method  should  always  be  overridden  in  order  to  replace  or  remove  the  Lockup  1 page  from  the 
object's  settings  notebook.  To  remove  the  page  from  the  settings  notebook,  the  override  method 
should  return  SETTINGS_PAGE_REMOVED  without  calling  the  parent  method.  To  replace  the  page 
with  another  page,  the  override  method  should  call  the  wpInsertSettingsPage  method  without  calling 
the  parent  method. 


Related  Methods 

See  Notebook  Control  Window  Messages  for  related  messages. 


• wpAddSettingsPages 

• wpInsertSettingsPage 
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wpAddDesktopLockup2Page 
WPDesktop  instance  method 


#define  INCL_WINWORKPLACE 


ULONG  wpAddDesktopLockup2Page  (WPDesktop  * self,  HWND  hwndNotebook) 


The  wpAddDesktopLockup2Page  instance  method  is  called  to  allow  the  object  to  add  the  Lockup  2 
page  to  its  settings  notebook. 

Parameters 

self  (WPDesktop  *)  - input 
The  pointer  to  this  object. 
hwndNotebook  (HWND)  - input 
The  settings  notebook  handle. 


Returns 

Page  identifier: 

0 Error  occurred. 

Pageld  Identifier  for  the  inserted  page. 

Usage 

This  method  must  only  be  called  from  within  an  override  of  the  wpAddSettingsPages  method. 


How  to  Override 

This  method  should  always  be  overridden  in  order  to  replace  or  remove  the  Lockup  2 page  from  the 
object's  settings  notebook.  To  remove  the  page  from  the  settings  notebook,  the  override  method 
should  return  SETTINGS_PAGE_REMOVED  without  calling  the  parent  method.  To  replace  the  page 
with  another  page,  the  override  method  should  call  the  wpinsertSettingsPage  method  without  calling 
the  parent  method. 


Related  Methods 

See  Notebook  Control  Window  Messages  for  related  messages. 


• wpAddSettingsPages 

• wpinsertSettingsPage 
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wp Add DesktopLockup3 Page  - 
WPDesktop  instance  method 


#define  INCL_WINWORKPLACE 


ULONG  wpAddDesktopLockup3Page  (WPDesktop  * self,  HWND  hwndNotebook) 


The  wpAddDesktopLockup3Page  instance  method  is  called  to  allow  the  object  to  add  the  Lockup  3 
page  to  its  settings  notebook. 

Parameters 

self  (WPDesktop  *)  - input 
The  pointer  to  this  object. 
hwndNotebook  (HWND)  - input 
The  settings  notebook  handle. 


Returns 

Page  identifier: 

0 Error  occurred. 

Pageld  Identifier  for  the  inserted  page. 

Usage 

This  method  must  only  be  called  from  within  an  override  of  the  wpAddSettingsPages  method. 


How  to  Override 

This  method  should  always  be  overridden  in  order  to  replace  or  remove  the  Lockup  3 page  from  the 
object's  settings  notebook.  To  remove  the  page  from  the  settings  notebook,  the  override  method 
should  return  SETTINGS _P AGE _REMOVED  without  calling  the  parent  method.  To  replace  the  page 
with  another  page,  the  override  method  should  call  the  wpinsertSettingsPage  method  without  calling 
the  parent  method. 


Related  Methods 

See  Notebook  Control  Window  Messages  for  related  messages. 


• wpAddSettingsPages 

• wpinsertSettingsPage 
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wpAddDiskDetailsPage 
WPDisk  instance  method 


#define  INCL_WINWORKPLACE 


ULONG  wpAddDiskDetailsPage  (WPDisk  * self,  HWND  hwndNotebook) 


The  wpAddDiskDetailsPage  instance  method  is  called  to  allow  the  object  to  add  the  Details  page  to 
its  settings  notebook. 

Parameters 

self  (WPDisk  *)  - input 

The  pointer  to  this  object. 
hwndNotebook  (HWND)  - input 
The  settings  notebook  handle. 


Returns 

Page  identifier: 

0 Error  occurred. 

Pageld  Identifier  for  the  inserted  page. 

Usage 

This  method  must  only  be  called  from  within  an  override  of  the  wpAddSettingsPages  method. 


How  to  Override 

This  method  should  always  be  overridden  in  order  to  replace  or  remove  the  Details  page  from  the 
object's  settings  notebook.  To  remove  the  page  from  the  settings  notebook,  the  override  method 
should  return  SETTINGS _P AGE _REMOVED  without  calling  the  parent  method.  To  replace  the  page 
with  another  page,  the  override  method  should  call  the  wpinsertSettingsPage  method  without  calling 
the  parent  method. 


Related  Methods 

See  Notebook  Control  Window  Messages  for  related  messages. 


• wpAddSettingsPages 

• wpinsertSettingsPage 
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wpAddFileMenuPage  - 
WP FileSystem  instance  method 


#define  INCL_WINWORKPLACE 


ULONG  wpAddFileMenuPage  (WPFIIeSystem  * self,  HWND  hwndNotebook) 


The  wpAddFileMenuPage  instance  method  is  called  to  allow  the  object  to  add  the  Menu  page  to  its 
settings  notebook. 


Parameters 

self  (WPFileSystem  *)  - input 
The  pointer  to  this  object. 
hwndNotebook  (HWND)  - input 
Settings  notebook  handle. 

Returns 

Page  identifier: 

0 Error  occurred. 

Pageld  Identifier  for  the  inserted  page. 


Usage 

This  method  must  only  be  called  from  within  an  override  of  the  wpAddSettingsPages  method. 


How  to  Override 

Method  should  always  be  overridden  in  order  to  replace  or  remove  the  Menu  page  from  the  object's 
settings  notebook. 


To  remove  the  page  from  the  settings  notebook,  the  override  method  should  return 
SETTINGS_PAGE_REMOVED  without  calling  the  parent  method.  To  replace  the  page  with  another 
page,  the  override  method  should  call  the  wpInsertSettingsPage  method  without  calling  the  parent 
method. 


Related  Methods 

See  Notebook  Control  Window  Messages  for  related  messages. 


• wpAddSettingsPages 

• wpInsertSettingsPage 
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wpAddFileTypePage  - 
WPDataFile  instance  method 


#define  INCL_WINWORKPLACE 


ULONG  wpAddFileTypePage  (WPDataFile  * self,  HWND  hwndNotebook) 


The  wpAddFileTypePage  instance  method  is  called  to  allow  the  object  to  add  the  Type  page  to  its 
settings  notebook. 

Parameters 

self  (WPDataFile  *)  - input 
The  pointer  to  this  object. 
hwndNotebook  (HWND)  - input 
The  settings  notebook  handle. 


Returns 

Page  identifier: 

0 Error  occurred. 

Pageld  Identifier  for  the  inserted  page. 

Usage 

This  method  must  only  be  called  from  within  an  override  of  the  wpAddSettingsPages  method. 


How  to  Override 

This  method  should  always  be  overridden  in  order  to  replace  or  remove  the  Type  page  from  the 
object's  settings  notebook.  To  remove  the  page  from  the  settings  notebook,  the  override  method 
should  return  SETTINGS_PAGE_REMOVED  without  calling  the  parent  method.  To  replace  the  page 
with  another  page,  the  override  method  should  call  the  wpinsertSettingsPage  method  without  calling 
the  parent  method. 


Related  Methods 

See  Notebook  Control  Window  Messages  for  related  messages. 


• wpAddSettingsPages 

• wpQueryType 

• wpSetTitle 
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wpAddFi  lei  Page  — 
WPFileSystem  instance  method 


#define  INCL_WINWORKPLACE 


ULONG  wpAddFllel  Page  (WPFileSystem  * self,  HWND  hwndNotebook) 


The  wpAddFilelPage  instance  method  is  called  to  allow  the  object  to  add  the  File  1 page  to  its 
settings  notebook. 

Parameters 

self  (WPFileSystem  *)  - input 
The  pointer  to  this  object. 
hwndNotebook  (HWND)  - input 
The  settings  notebook  handle. 


Returns 

Page  identifier: 

0 Error  occurred. 

Pageld  Identifier  for  the  inserted  page. 

Usage 

This  method  must  only  be  called  from  within  an  override  of  the  wpAddSettingsPages  method. 

How  to  Override 

This  method  should  always  be  overridden  in  order  to  replace  or  remove  the  File  1 page  from  the 
object's  settings  notebook.  To  remove  the  page  from  the  settings  notebook,  the  override  method 
should  return  SETTINGS_PAGE_REMOVED  without  calling  the  parent  method.  To  replace  the  page 
with  another  page,  the  override  method  should  call  the  wpInsertSettingsPage  method  without  calling 
the  parent  method. 


Related  Methods 

See  Notebook  Control  Window  Messages  for  related  messages. 


• wpAddSettingsPages 

• wpInsertSettingsPage 


Chapter  9.  Workplace  Classes,  Instance  Methods,  and  Class  Methods 


9-67 


wpAddFile2Page  - 
WPFileSystem  instance  method 


#define  INCL_WINWORKPLACE 


ULONG  wpAddFile2Page  (WPFileSystem  * self,  HWND  hwndNotebook) 


The  wpAddFile2Page  instance  method  is  called  to  allow  the  object  to  add  the  File  2 page  to  its 
settings  notebook. 

Parameters 

self  (WPFileSystem  *)  - input 
The  pointer  to  this  object. 
hwndNotebook  (HWND)  - input 
The  settings  notebook  handle. 


Returns 

Page  identifier: 

0 Error  occurred. 

Pageld  Identifier  for  the  inserted  page. 

Usage 

This  method  must  only  be  called  from  within  an  override  of  the  wpAddSettingsPages  method. 


How  to  Override 

This  method  should  always  be  overridden  in  order  to  replace  or  remove  the  File  2 page  from  the 
object's  settings  notebook.  To  remove  the  page  from  the  settings  notebook,  the  override  method 
should  return  SETTINGS_PAGE_RE MO VED  without  calling  the  parent  method.  To  replace  the  page 
with  another  page,  the  override  method  should  call  the  wpInsertSettingsPage  method  without  calling 
the  parent  method. 


Related  Methods 

See  Notebook  Control  Window  Messages  for  related  messages. 


• wpAddSettingsPages 

• wpInsertSettingsPage 
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wpAddFile3Page  - 
WPFileSystem  instance  method 


#define  INCL_WINWORKPLACE 


ULONG  wpAddFlle3Page  (WPFileSystem  * self,  HWNO  hwndNotebook) 


The  wpAddFile3Page  instance  method  is  called  to  allow  the  object  to  add  the  File  3 page  to  its 
settings  notebook. 

Parameters 

self  (WPFileSystem  *)  - input 
The  pointer  to  this  object. 
hwndNotebook  (HWND)  - input 
The  settings  notebook  handle. 


Returns 

Page  identifier: 

0 Error  occurred. 

Pageld  Identifier  for  the  inserted  page. 

Usage 

This  method  must  only  be  called  from  within  an  override  of  the  wpAddSettingsPages  method. 

How  to  Override 

This  method  should  always  be  overridden  in  order  to  replace  or  remove  the  File  3 page  from  the 
object's  settings  notebook.  To  remove  the  page  from  the  settings  notebook,  the  override  method 
should  return  SETTINGS_PAGE_REMOVED  without  calling  the  parent  method.  To  replace  the  page 
with  another  page,  the  override  method  should  call  the  wpinsertSettingsPage  method  without  calling 
the  parent  method. 


Related  Methods 

See  Notebook  Control  Window  Messages  for  related  messages. 


• wpAddSettingsPages 

• wpinsertSettingsPage 
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wpAddFolderBackgroundPage 
WPFolder  instance  method 


#define  INCL.WINWORKPLACE 


ULONG  wpAddFolderBackgroundPage  (WPFolder  * self,  HWND  hwndNotebook) 


The  wpAddFolderBackgroundPage  instance  method  is  called  to  allow  the  object  to  add  the 
Background  page  to  its  settings  notebook. 

Parameters 

self  (WPFolder  *)  - input 
The  pointer  to  this  object. 
hwndNotebook  (HWND)  - input 
The  settings  notebook  handle. 


Returns 

Page  identifier: 

0 Error  occurred. 

Pageld  Identifier  for  the  inserted  page. 

Usage 

This  method  must  only  be  called  from  within  an  override  of  the  wpAddSettingsPages  method. 


How  to  Override 

This  method  should  always  be  overridden  in  order  to  replace  or  remove  the  Background  page  from 
the  object's  settings  notebook.  To  remove  the  page  from  the  settings  notebook,  the  override  method 
should  return  SETTINGS_PAGE_REMOVED  without  calling  the  parent  method.  To  replace  the  page 
with  another  page,  the  override  method  should  call  the  wpInsertSettingsPage  method  without  calling 
the  parent  method. 


Related  Methods 

See  Notebook  Control  Window  Messages  for  related  messages. 

• wpAddSettingsPages 

• wpInsertSettingsPage 
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wpAddFolderlncludePage  - 
WPFolder  instance  method 


#define  INCL_WINWORKPLACE 


ULONG  wpAddFolderlncludePage  (WPFolder  * self,  HWNO  hwndNotebook) 


The  wpAddFolderlncludePage  instance  method  is  called  to  allow  the  object  to  add  the  Include  page 
to  Its  settings  notebook. 

Parameters 

self  (WPFolder  *)  - input 
The  pointer  to  this  object. 
hwndNotebook  (HWND)  - input 
The  settings  notebook  handle. 


Returns 

Page  identifier: 

0 Error  occurred. 

Pageld  Identifier  for  the  inserted  page. 

Usage 

This  method  must  only  be  called  from  within  an  override  of  the  wpAddSettingsPages  method. 


How  to  Override 

This  method  should  always  be  overridden  in  order  to  replace  or  remove  th e Include  page  from  the 
object's  settings  notebook.  To  remove  the  page  from  the  settings  notebook,  the  override  method 
should  return  SETTINGS_PAGE_REMOVED  without  calling  the  parent  method.  To  replace  the  page 
with  another  page,  the  override  method  should  call  the  wpInsertSettingsPage  method  without  calling 
the  parent  method. 


Related  Methods 

See  Notebook  Control  Window  Messages  for  related  messages. 


• wpAddSettingsPages 

• wpInsertSettingsPage 
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wpAddFolderSortPage  - 
WPFolder  instance  method 


#define  INCL_WINWORKPLACE 


ULONG  wpAddFolderSortPage  (WPFolder  * self,  HWND  hwndNotebook) 


The  wpAddFolderSortPage  instance  method  is  called  to  allow  the  object  to  add  the  Sort  page  to  its 
settings  notebook. 

Parameters 

self  (WPFolder  *)  - input 
The  pointer  to  this  object. 
hwndNotebook  (HWND)  - input 
The  settings  notebook  handle. 


Returns 

Page  identifier: 

0 Error  occurred. 

Pageld  Identifier  for  the  inserted  page. 

Usage 

This  method  must  only  be  called  from  within  an  override  of  the  wpAddSettingsPages  method. 


How  to  Override 

This  method  should  always  be  overridden  in  order  to  replace  or  remove  the  Sort  page  from  the 
object's  settings  notebook.  To  remove  the  page  from  the  settings  notebook,  the  override  method 
should  return  SETTINGS_PAGE_REMOVED  without  calling  the  parent  method.  To  replace  the  page 
with  another  page,  the  override  method  should  call  the  wpInsertSettingsPage  method  without  calling 
the  parent  method. 


Related  Methods 

See  Notebook  Control  Window  Messages  for  related  messages. 


• wpAddSettingsPages 

• wpInsertSettingsPage 
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wp AddFolderViewl  Page  - 
WPFolder  instance  method 


#define  INCL_WINWORKPLACE 


ULONG  wp  AddFolderViewl  Page  (WPFolder  * self,  HWND  hwndNotebook) 


The  wpAddFolderViewIPage  instance  method  is  called  to  allow  the  object  to  add  the  View  1 page  to 
its  settings  notebook. 

Parameters 

self  (WPFolder  *)  - input 
The  pointer  to  this  object. 
hwndNotebook  (HWND)  - input 
The  settings  notebook  handle. 


Returns 

Page  identifier: 

0 Error  occurred. 

Pageld  Identifier  for  the  inserted  page. 

Usage 

This  method  must  only  be  called  from  within  an  override  of  the  wpAddSettingsPages  method. 


How  to  Override 

This  method  should  always  be  overridden  in  order  to  replace  or  remove  the  View  1 page  from  the 
object's  settings  notebook.  To  remove  the  page  from  the  settings  notebook,  the  override  method 
should  return  SETTINGS_PAGE_REMOVED  without  calling  the  parent  method.  To  replace  the  page 
with  another  page,  the  override  method  should  call  the  wpinsertSettingsPage  method  without  calling 
the  parent  method. 


Related  Methods 

See  Notebook  Control  Window  Messages  for  related  messages. 


• wpAddSettingsPages 

• wpinsertSettingsPage 


Chapter  9.  Workplace  Classes,  Instance  Methods,  and  Class  Methods 


9-73 


wpAddFolderView2Page  - 
WPFolder  instance  method 


#define  INCL_WINWORKPLACE 


ULONG  wpAddFolderVlew2Page  (WPFolder  * self,  HWND  hwndNotebook) 


The  wpAddFolderView2Page  instance  method  is  called  to  allow  the  object  to  add  the  View  2 page  to 
its  settings  notebook. 

Parameters 

self  (WPFolder  *)  - input 
The  pointer  to  this  object. 
hwndNotebook  (HWND)  - input 
The  settings  notebook  handle. 


Returns 

Page  identifier: 

0 Error  occurred. 

Pageld  Identifier  for  the  inserted  page. 

Usage 

This  method  must  only  be  called  from  within  an  override  of  the  wpAddSettingsPages  method. 


How  to  Override 

This  method  should  always  be  overridden  in  order  to  replace  or  remove  the  View  2 page  from  the 
object's  settings  notebook.  To  remove  the  page  from  the  settings  notebook,  the  override  method 
should  return  SETTINGS_PAGE_REMOVED  without  calling  the  parent  method.  To  replace  the  page 
with  another  page,  the  override  method  should  call  the  wpinsertSettingsPage  method  without  calling 
the  parent  method. 


Related  Methods 

See  Notebook  Control  Window  Messages  for  related  messages. 


• wpAddSettingsPages 

• wpinsertSettingsPage 
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wpAddFolderView3Page  - 
WPFolder  instance  method 


#define  INCL_WINWORKPLACE 


ULONG  wpAddFolderVlew3Page  (WPFolder  * self,  HWNO  hwndNotebook) 


The  wpAddFolderView3Page  instance  method  is  called  to  allow  the  object  to  add  the  View  3 page  to 
its  settings  notebook. 

Parameters 

self  (WPFolder  *)  - input 
The  pointer  to  this  object. 
hwndNotebook  (HWND)  - input 
The  settings  notebook  handle. 


Returns 

Page  identifier: 

0 Error  occurred. 

Pageld  Identifier  for  the  inserted  page. 

Usage 

This  method  must  only  be  called  from  within  an  override  of  the  wpAddSettingsPages  method. 


How  to  Override 

This  method  should  always  be  overridden  in  order  to  replace  or  remove  the  View  3 page  from  the 
object's  settings  notebook.  To  remove  the  page  from  the  settings  notebook,  the  override  method 
should  return  SETTINGS_PAGE_REMOVED  without  calling  the  parent  method.  To  replace  the  page 
with  another  page,  the  override  method  should  call  the  wpinsertSettingsPage  method  without  calling 
the  parent  method. 


Related  Methods 

See  Notebook  Control  Window  Messages  for  related  messages. 


• wpAddSettingsPages 

• wpinsertSettingsPage 
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wpAddKeyboardMappingsPage 
WPKeyboard  instance  method 


^define  INCL_WINWORKPLACE 


ULONG  wpAddKeyboardMappingsPage  (WPKeyboard  * sell,  HWND  hwndNotebook) 


The  wpAddKeyboardMappingsPage  instance  method  is  called  to  allow  the  object  to  add  the 
Mappings  page  to  its  settings  notebook. 

Parameters 

self  (WPKeyboard  *)  - input 
The  pointer  to  this  object. 
hwndNotebook  (HWND)  - input 
The  settings  notebook  handle. 


Returns 

Page  identifier: 

0 Error  occurred. 

Pageld  Identifier  for  the  inserted  page. 

Usage 

This  method  must  only  be  called  from  within  an  override  of  the  wpAddSettingsPages  method. 


How  to  Override 

This  method  should  always  be  overridden  in  order  to  replace  or  remove  the  Mappings  page  from  the 
object's  settings  notebook.  To  remove  the  page  from  the  settings  notebook,  the  override  method 
should  return  SETTINGS_PAGE_REMOVED  without  calling  the  parent  method.  To  replace  the  page 
with  another  page,  the  override  method  should  call  the  wpinsertSettingsPage  method  without  calling 
the  parent  method. 


Related  Methods 

See  Notebook  Control  Window  Messages  for  related  messages. 


• wpAddSettingsPages 

• wpinsertSettingsPage 
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wpAddKeyboardSpecialNeedsPage  - 
WPKeyboard  instance  method 


#define  INCL_WINWORKPLACE 


ULONG  wpAddKeyboardSpecialNeedsPage  (WPKeyboard  * self,  HWND  hwndNotebook) 


The  wpAddKeyboardSpecialNeedsPage  instance  method  is  called  to  allow  the  object  to  add  the 
Special  Needs  page  to  its  settings  notebook. 

Parameters 

self  (WPKeyboard  *)  - input 
The  pointer  to  this  object. 
hwndNotebook  (HWND)  - input 
The  settings  notebook  handle. 


Returns 

Page  identifier: 

0 Error  occurred. 

Pageld  Identifier  for  the  inserted  page. 

Usage 

This  method  must  only  be  called  from  within  an  override  of  the  wpAddSettingsPages  method. 


How  to  Override 

This  method  should  always  be  overridden  in  order  to  replace  or  remove  the  Special  Needs  page 
from  the  object's  settings  notebook.  To  remove  the  page  from  the  settings  notebook,  the  override 
method  should  return  SETTINGS_PAGE_REMOVED  without  calling  the  parent  method.  To  replace  the 
page  with  another  page,  the  override  method  should  call  the  wpinsertSettingsPage  method  without 
calling  the  parent  method. 


Related  Methods 

See  Notebook  Control  Window  Messages  for  related  messages. 


• wpAddSettingsPages 

• wpinsertSettingsPage 
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wpAddKeyhoardTimingPage 
WPKeyboard  instance  method 


#define  INCL_WINWORKPLACE 


ULONG  wpAddKeyboardTimingPage  (WPKeyboard  * self,  HWND  hwndNotebook) 


The  wpAddKeyboardTimingPage  instance  method  is  called  to  allow  the  object  to  add  the  Timing 
page  to  its  settings  notebook. 

Parameters 

self  (WPKeyboard  *)  - input 
The  pointer  to  this  object. 
hwndNotebook  (HWND)  - input 
The  settings  notebook  handle. 


Returns 

Page  identifier: 

0 Error  occurred. 

Pageld  Identifier  for  the  inserted  page. 

Usage 

This  method  must  only  be  called  from  within  an  override  of  the  wpAddSettingsPages  method. 

How  to  Override 

This  method  should  always  be  overridden  in  order  to  replace  or  remove  the  Timing  page  from  the 
object's  settings  notebook.  To  remove  the  page  from  the  settings  notebook,  the  override  method 
should  return  SETTINGS_PAGE_REMOVED  without  calling  the  parent  method.  To  replace  the  page 
with  another  page,  the  override  method  should  call  the  wpinsertSettingsPage  method  without  calling 
the  parent  method. 


Related  Methods 

See  Notebook  Control  Window  Messages  for  related  messages. 


• wpAddSettingsPages 

• wpinsertSettingsPage 
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wpAddMouseMappingsPage  - 
WPMouse  instance  method 


#define  INCL_WINWORKPLACE 


ULONG  wpAddMouseMappingsPage  (WPMouse  * self,  HWND  hwndNotebook) 


The  wpAddMouseMappingsPage  instance  method  is  called  to  allow  the  object  to  add  the  Mappings 
page  to  its  settings  notebook. 


Parameters 

self  (WPMouse  *)  - input 
The  pointer  to  this  object. 
hwndNotebook  (HWND)  - input 
The  settings  notebook  handle. 


Returns 

Page  identifier: 

0 Error  occurred. 

Pageld  Identifier  for  the  inserted  page. 

Usage 

This  method  must  only  be  called  from  within  an  override  of  the  wpAddSettingsPages  method. 


How  to  Override 

The  method  should  always  be  overridden  in  order  to  replace  or  remove  the  Mappings  page  from  the 
object's  settings  notebook.  To  remove  the  page  from  the  settings  notebook,  the  override  method 
should  return  SETTINGS_PAGE_REMOVED  without  calling  the  parent  method.  To  replace  the  page 
with  another  page,  the  override  method  should  call  the  wpinsertSettingsPage  method  without  calling 
the  parent  method. 


Related  Methods 

See  Notebook  Control  Window  Messages  for  related  messages. 


• wpAddSettingsPages 

• wpinsertSettingsPage 
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wpAddMouseTimingPage 
WPMouse  instance  method 


#define  INCL_WINWORKPLACE 


ULONG  wpAddMouseTimingPage  (WPMouse  * self,  HWND  hwndNotebook) 


The  wpAddMouseTimingPage  instance  method  is  called  to  allow  the  object  to  add  the  Timing  page 
to  its  settings  notebook. 


Parameters 

self  (WPMouse  *)  - input 
The  pointer  to  this  object. 
hwndNotebook  (HWND)  - input 
The  settings  notebook  handle. 


Returns 

Page  identifier: 

0 Error  occurred. 

Pageld  Identifier  for  the  inserted  page. 

Usage 

This  method  must  only  be  called  from  within  an  override  of  the  wpAddSettingsPages  method. 


How  to  Override 

This  method  should  always  be  overridden  in  order  to  replace  or  remove  the  Timing  page  from  the 
object's  settings  notebook.  To  remove  the  page  from  the  settings  notebook,  the  override  method 
should  return  SETTINGS_PAGE_REMOVED  without  calling  the  parent  method.  To  replace  the  page 
with  another  page,  the  override  method  should  call  the  wpInsertSettingsPage  method  without  calling 
the  parent  method. 


Related  Methods 

See  Notebook  Control  Window  Messages  for  related  messages. 


• wpAddSettingsPages 

• wpInsertSettingsPage 
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wpAddMouseTypePage  - 
WPMouse  instance  method 


#define  INCL_WINWORKPLACE 


ULONG  wpAddMouseTypePage  (WPMouse  * self,  HWND  hwndNotebook) 


The  wpAddMouseTypePage  instance  method  is  called  to  allow  the  object  to  add  the  Type  page  to  its 
settings  notebook. 

Parameters 

self  (WPMouse  *)  - input 
The  pointer  to  this  object. 
hwndNotebook  (HWND)  - input 
The  settings  notebook  handle. 


Returns 

Page  identifier: 

0 Error  occurred. 

Pageld  Identifier  for  the  inserted  page. 

Usage 

This  method  must  only  be  called  from  within  an  override  of  the  wpAddSettingsPages  method. 


How  to  Override 

This  method  should  always  be  overridden  in  order  to  replace  or  remove  the  Type  page  from  the 
object's  settings  notebook.  To  remove  the  page  from  the  settings  notebook,  the  override  method 
should  return  SETTINGS_PAGE_REMOVED  without  calling  the  parent  method.  To  replace  the  page 
with  another  page,  the  override  method  should  call  the  wpinsertSettingsPage  method  without  calling 
the  parent  method. 


Related  Methods 

See  Notebook  Control  Window  Messages  for  related  messages. 


• wpAddSettingsPages 

• wpinsertSettingsPage 
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wpAddObjectGeneralPage 
WPObject  instance  method 


#define  INCL_WINWORKPLACE 


ULONG  wpAddObjectGeneralPage  (WPObject  * self,  HWND  hwndNotebook) 


The  wpAddObjectGeneralPage  instance  method  is  called  to  allow  the  object  to  add  the  General  page 
to  Its  settings  notebook. 

Parameters 

self  (WPObject  *)  - input 
The  pointer  to  this  object. 
hwndNotebook  (HWND)  - input 
The  settings  notebook  handle. 


Returns 

Page  identifier: 

0 Error  occurred. 

Pageld  Identifier  for  the  inserted  page. 

Usage 

This  method  must  only  be  called  from  within  an  override  of  the  wpAddSettingsPages  method. 


How  to  Override 

This  method  should  always  be  overridden  in  order  to  replace  or  remove  the  General  page  from  the 
object's  settings  notebook.  To  remove  the  page  from  the  settings  notebook,  the  override  method 
should  return  SETTINGS_PAGE_REMOVED  without  calling  the  parent  method.  To  replace  the  page 
with  another  page,  the  override  method  should  call  the  wpInsertSettingsPage  method  without  calling 
the  parent  method. 


Related  Methods 

See  Notebook  Control  Window  Messages  for  related  messages. 


• wpAddSettingsPages 

• wpInsertSettingsPage 
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wpAddProgramAssociationPage  - 
WPProgramFile  instance  method 


#define  INCL_WINWORKPLACE 


ULONG  wpAddProgramAssociationPage  (WPProgramFile  * self,  HWND  hwndNotebook) 


The  wpAddProgramAssociationPage  instance  method  is  called  to  allow  the  object  to  add  the 
Association  page  to  its  settings  notebook. 

Parameters 

self  (WPProgramFile  *)  - input 
The  pointer  to  this  object. 
hwndNotebook  (HWND)  - input 
The  settings  notebook  handle. 


Returns 

Page  identifier: 

0 Error  occurred. 

Pageld  Identifier  for  the  inserted  page. 

Usage 

This  method  must  only  be  called  from  within  an  override  of  the  wpAddSettingsPages  method. 


How  to  Override 

This  method  should  always  be  overridden  in  order  to  replace  or  remove  the  Association  page  from 
the  object's  settings  notebook.  To  remove  the  page  from  the  settings  notebook,  the  override  method 
should  return  SETTINGS_PAGE_REMOVED  without  calling  the  parent  method.  To  replace  the  page 
with  another  page,  the  override  method  should  call  the  wpInsertSettingsPage  method  without  calling 
the  parent  method. 


Related  Methods 

See  Notebook  Control  Window  Messages  for  related  messages. 


• wpAddSettingsPages 

• wpInsertSettingsPage 
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wpAddProgramAssociationPage 
WPProgram  instance  method 


#define  INCL_WINWORKPLACE 


ULONG  wpAddProgramAssociationPage  (WPProgramFlle  * self,  HWND  hwndNotebook) 


The  wpAddProgramAssociationPage  instance  method  is  called  to  allow  the  object  to  add  the 
Association  page  to  its  settings  notebook. 

Parameters 

self  (WPProgramFile  *)  - input 
The  pointer  to  this  object. 
hwndNotebook  (HWND)  - input 
The  settings  notebook  handle. 


Returns 

Page  identifier: 

0 Error  occurred. 

Pageld  Identifier  for  the  inserted  page. 

Usage 

This  method  must  only  be  called  from  within  an  override  of  the  wpAddSettingsPages  method. 


How  to  Override 

This  method  should  always  be  overridden  in  order  to  replace  or  remove  the  Association  page  from 
the  object's  settings  notebook.  To  remove  the  page  from  the  settings  notebook,  the  override  method 
should  return  SETTINGS_PAGE_REMOVED  without  calling  the  parent  method.  To  replace  the  page 
with  another  page,  the  override  method  should  call  the  wpInsertSettingsPage  method  without  calling 
the  parent  method. 


Related  Methods 

See  Notebook  Control  Window  Messages  for  related  messages. 


• wpAddSettingsPages 

• wpInsertSettingsPage 
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wpAddProgramPage  - 
WPProgram  instance  method 


#define  INCL_WINWORKPLACE 


ULONG  wpAddProgramPage  (WPProgram  * self,  HWND  hwndNotebook) 


The  wpAddProgramPage  instance  method  is  called  to  allow  the  object  to  add  the  Program  page  to  its 
settings  notebook. 


Parameters 

self  (WPProgram  *)  - input 
The  pointer  to  this  object. 
hwndNotebook  (HWND)  - input 
Settings  notebook  handle. 

Returns 

Page  identifier: 

0 Error  occurred. 

Pageld  Identifier  for  the  inserted  page. 


Usage 

This  method  must  only  be  called  from  within  an  override  of  the  wpAddSettingsPages  method. 


How  to  Override 

This  method  should  always  be  overridden  in  order  to  replace  or  remove  the  Program  page  from  the 
object's  settings  notebook.  To  remove  the  page  from  the  settings  notebook,  the  override  method 
should  return  SETTINGS_PAGE_REMOVED  without  calling  the  parent  method.  To  replace  the  page 
with  another  page,  the  override  method  should  call  the  wpInsertSettingsPage  method  without  calling 
the  parent  method. 


Related  Methods 

See  Notebook  Control  Window  Messages  for  related  messages. 


• wpAddSettingsPages 

• wpInsertSettingsPage 
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wpAddProgramPage  - 
WPProgramFile  instance  method 


#define  INCL_WINWORKPLACE 


ULONG  wpAddProgramPage  (WPProgramFile  * self,  HWND  hwndNotebook) 


The  wpAddProgramPage  instance  method  is  called  to  allow  the  object  to  add  the  Program  page  to  its 
settings  notebook. 

Parameters 

self  (WPProgramFile  *)  - input 
The  pointer  to  this  object. 
hwndNotebook  (HWND)  - input 
Settings  notebook  handle. 

Returns 

Page  identifier: 

0 Error  occurred. 

Pageld  Identifier  for  the  inserted  page. 


Usage 

This  method  must  only  be  called  from  within  an  override  of  the  wpAddSettingsPages  method. 


How  to  Override 

This  method  should  always  be  overridden  in  order  to  replace  or  remove  the  Program  page  from  the 
object's  settings  notebook.  To  remove  the  page  from  the  settings  notebook,  the  override  method 
should  return  SETT INGS_PA GE_REMOVED  without  calling  the  parent  method.  To  replace  the  page 
with  another  page,  the  override  method  should  call  the  wpinsertSettingsPage  method  without  calling 
the  parent  method. 


Related  Methods 

See  Notebook  Control  Window  Messages  for  related  messages. 


• wpAddSettingsPages 

• wpinsertSettingsPage 
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wpAddProgramSessionPage  - 
WPProgram  instance  method 


#define  INCL_WINWORKPLACE 


ULONG  wpAddProgramSessionPage  (WPProgram  * sell,  HWND  hwndNotebook) 


The  wpAddProgramSessionPage  instance  method  is  called  to  allow  the  object  to  add  the  Session 
page  to  its  settings  notebook. 

Parameters 

sell  (WPProgram  *)  - input 
The  pointer  to  this  object. 
hwndNotebook  (HWND)  - input 
The  settings  notebook  handle. 


Returns 

Page  identifier: 

0 Error  occurred. 

Pageld  Identifier  for  the  inserted  page. 

Usage 

This  method  must  only  be  called  from  within  an  override  of  the  wpAddSettingsPages  method. 


How  to  Override 

This  method  should  always  be  overridden  in  order  to  replace  or  remove  the  Session  page  from  the 
object's  settings  notebook.  To  remove  the  page  from  the  settings  notebook,  the  override  method 
should  return  SETTINGS_PAGE_REMOVED  without  calling  the  parent  method.  To  replace  the  page 
with  another  page,  the  override  method  should  call  the  wpInsertSettingsPage  method  without  calling 
the  parent  method. 


Related  Methods 

See  Notebook  Control  Window  Messages  for  related  messages. 


• wpAddSettingsPages 

• wpInsertSettingsPage 
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wpAddProgramSessionPage  - 
WPProgramFile  instance  method 


#define  INCL_WINWORKPLACE 


ULONG  wpAddProgramSessionPage  (WPProgramFile  * self,  HWND  hwndNotebook) 


The  wpAddProgramSessionPage  instance  method  is  called  to  allow  the  object  to  add  the  Session 
page  to  its  settings  notebook. 

Parameters 

self  (WPProgramFile  *)  - input 
The  pointer  to  this  object. 
hwndNotebook  (HWND)  - input 
The  settings  notebook  handle. 


Returns 

Page  identifier: 

0 Error  occurred. 

Pageld  Identifier  for  the  inserted  page. 

Usage 

This  method  must  only  be  called  from  within  an  override  of  the  wpAddSettingsPages  method. 


How  to  Override 

This  method  should  always  be  overridden  in  order  to  replace  or  remove  the  Session  page  from  the 
object's  settings  notebook.  To  remove  the  page  from  the  settings  notebook,  the  override  method 
should  return  SETTINGS_PAGE_REMOVED  without  calling  the  parent  method.  To  replace  the  page 
with  another  page,  the  override  method  should  call  the  wpInsertSettingsPage  method  without  calling 
the  parent  method. 


Related  Methods 

See  Notebook  Control  Window  Messages  for  related  messages. 


• wpAddSettingsPages 

• wpInsertSettingsPage 
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wpAddSettingsPages  - 
WPObject  instance  method 


#define  INCL_WINWORKPLACE 


BOOL  wpAddSettingsPages  (WPObject  * self,  HWND  hwndNotebook) 


The  wpAddSettingsPages  instance  method  is  called  to  allow  the  object  to  add  all  of  its  settings  pages 
to  its  settings  notebook. 

Parameters 

seif  (WPObject  *)  - input 
The  pointer  to  this  object. 
hwndNotebook  (HWND)  - input 
The  settings  notebook  handle. 


Returns 

Success  indicator: 

TRUE  Successful  completion. 

FALSE  Error  occurred. 

Usage 

This  method  is  generally  only  called  by  the  system. 


How  to  Override 

This  method  should  always  be  overridden  in  order  to  add  pages  to  the  settings  notebook  or  to 
remove  them.  To  add  a page  to  the  settings  notebook,  a call  to  the  wpinsertSettingsPage  method  is 
required.  To  remove  a page  from  the  settings  notebook,  the  method  that  adds  the  page  to  the 
settings  notebook  should  be  overridden  and  return  SETTINGS_PAGE_REMOVED  without  calling  its 
parent  method. 

In  most  cases,  the  parent  method  should  be  called  first.  Calling  the  parent  method  first  will  put 
pages  added  by  this  method  at  the  top  of  the  settings  notebook,  above  the  pages  added  by  ancestor 
classes.  Calling  the  parent  last  will  put  pages  added  by  this  class  at  the  bottom  of  the  settings 
notebook,  below  the  pages  added  by  ancestor  classes. 


Related  Methods 

See  Notebook  Control  Window  Messages  for  related  messages. 
• wpinsertSettingsPage 
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wpAddSoundWarningBeepPage 
WPSound  instance  method 


#define  INCL_WINWORKPLACE 


ULONG  wpAddSoundWarningBeepPage  (WPSound  * self,  HWND  hwndNotebook) 


The  wpAddSoundWarningBeepPage  instance  method  is  called  to  allow  the  object  to  add  the  Warning 
Beep  page  to  its  settings  notebook. 


Parameters 

self  (WPSound  *)  - input 
The  pointer  to  this  object. 
hwndNotebook  (HWND)  - input 
The  settings  notebook  handle. 


Returns 

Page  identifier: 

0 Error  occurred. 

Pageld  Identifier  for  the  inserted  page. 

Usage 

This  method  must  only  be  called  from  within  an  override  of  the  wpAddSettingsPages  method. 


How  to  Override 

This  method  should  always  be  overridden  in  order  to  replace  or  remove  the  Warning  Beep  page  from 
the  object's  settings  notebook.  To  remove  the  page  from  the  settings  notebook,  the  override  method 
should  return  SETTINGS_PAGE_REMOVED  without  calling  the  parent  method.  To  replace  the  page 
with  another  page,  the  override  method  should  call  the  wpInsertSettingsPage  method  without  calling 
the  parent  method. 

Related  Methods 

See  Notebook  Control  Window  Messages  for  related  messages. 

• wpAddSettingsPages 

• wpInsertSettingsPage 
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wpAddSystemConfirmationPage  - 
WPSystem  instance  method 


#define  INCL_WINWORKPLACE 


ULONG  wpAddSystemConfirmationPage  (WPSystem  * seif,  HWND  hwndNotebook) 


The  wpAddSystemConfirmationPage  instance  method  is  called  to  allow  the  object  to  add  the 
Confirmation  page  to  its  settings  notebook. 

Parameters 

seif  (WPSystem  *)  - input 
The  pointer  to  this  object. 
hwndNotebook  (HWND)  - input 
The  settings  notebook  handle. 


Returns 

Page  identifier: 

0 Error  occurred. 

Pageld  Identifier  for  the  inserted  page. 

Usage 

This  method  must  only  be  called  from  within  an  override  of  the  wpAddSettingsPages  method. 


How  to  Override 

This  method  should  always  be  overridden  in  order  to  replace  or  remove  the  Confirmation  page  from 
the  object's  settings  notebook.  To  remove  the  page  from  the  settings  notebook,  the  override  method 
should  return  SETTINGS_PAGE_REMOVED  without  calling  the  parent  method.  To  replace  the  page 
with  another  page,  the  override  method  should  call  the  wpinsertSettingsPage  method  without  calling 
the  parent  method. 

Related  Methods 

See  Notebook  Control  Window  Messages  for  related  messages. 

• wpAddSettingsPages 

• wpinsertSettingsPage 
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wpAddSystemLogoPage  - 
WPSystem  instance  method 


#define  INCL_WINWORKPLACE 


ULONG  wpAddSystemLogoPage  (WPSystem  * self,  HWND  hwndNotebook) 


The  wpAddSystemLogoPage  instance  method  is  called  to  allow  the  object  to  add  the  Logo  page  to  its 
settings  notebook. 

Parameters 

self  (WPSystem  *)  - input 
The  pointer  to  this  object. 
hwndNotebook  (HWND)  - input 
The  settings  notebook  handle. 


Returns 

Page  identifier: 

0 Error  occurred. 

Pageld  Identifier  for  the  inserted  page. 

Usage 

This  method  must  only  be  called  from  within  an  override  of  the  wpAddSettingsPages  method. 


How  to  Override 

This  method  should  always  be  overridden  in  order  to  replace  or  remove  the  Logo  page  from  the 
object's  settings  notebook.  To  remove  the  page  from  the  settings  notebook,  the  override  method 
should  return  SETTINGS _P AGE _REMOV ED  without  calling  the  parent  method.  To  replace  the  page 
with  another  page,  the  override  method  should  call  the  wpinsertSettingsPage  method  without  calling 
the  parent  method. 


Related  Methods 

See  Notebook  Control  Window  Messages  for  related  messages. 


• wpAddSettingsPages 

• wpinsertSettingsPage 
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wpAddSystemPrintScreenPage  - 
WPSystem  instance  method 


#define  INCL_WINWORKPLACE 


ULONG  wpAddSystemPrintScreenPage  (WPSystem  * self,  HWND  hwndNotebook) 


The  wpAddSystemPrintScreenPage  instance  method  is  called  to  allow  the  object  to  add  the  Print 
Screen  page  to  its  settings  notebook. 

Parameters 

self  (WPSystem  *)  - input 
The  pointer  to  the  object. 
hwndNotebook  (HWND)  - input 
The  settings  notebook  handle. 


Returns 

Page  identifier. 

0 Error  occurred. 

Pageld  Identifier  for  the  inserted  page. 

Usage 

This  method  must  only  be  called  from  within  an  override  of  the  wpAddSettingsPages  method. 


How  to  Override 

This  method  should  always  be  overridden  in  order  to  replace  or  remove  the  Print  Screen  page  from 
the  object's  settings  notebook.  To  remove  the  page  from  the  settings  notebook,  the  override  method 
should  return  SETTINGS_PAGE_REMOVED  without  calling  the  parent  method.  To  replace  the  page 
with  another  page,  the  override  method  should  call  the  wpinsertSettingsPage  method  without  calling 
the  parent  method. 


Related  Methods 

• wpAddSettingsPages 

• wpinsertSettingsPage 
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wpAddSystemWindowPage 
WPSystem  instance  method 


#define  INCL_WINWORKPLACE 


ULONG  wpAddSystemWindowPage  (WPSystem  * self,  HWND  hwndNotebook) 


The  wpAddSystemWindowPage  instance  method  is  called  to  allow  the  object  to  add  the  Window 
page  to  its  settings  notebook. 


Parameters 

self  (WPSystem  *)  - input 
The  pointer  to  this  object. 
hwndNotebook  (HWND)  - input 
The  settings  notebook  handle. 


Returns 

Page  identifier: 

0 Error  occurred. 

Pageld  Identifier  for  the  inserted  page. 

Usage 

This  method  must  only  be  called  from  within  an  override  of  the  wpAddSettingsPages  method. 


How  to  Override 

This  method  should  always  be  overridden  in  order  to  replace  or  remove  the  Window  page  from  the 
object's  settings  notebook.  To  remove  the  page  from  the  settings  notebook,  the  override  method 
should  return  SETTINGS_PAGE_REMOVED  without  calling  the  parent  method.  To  replace  the  page 
with  another  page,  the  override  method  should  call  the  wpinsertSettingsPage  method  without  calling 
the  parent  method. 


Related  Methods 

See  Notebook  Control  Window  Messages  for  related  messages. 


• wpAddSettingsPages 

• wpinsertSettingsPage 


9-94  PM  Programming  Reference 


wpAddToObj  Use  List  - 
WPObject  instance  method 


#define  INCL_WINWORKPLACE 


BOOL  wpAddT oObjUseLlst  (WPObject  * self,  PUSEITEM  pUseltem) 


The  wpAddToObjUseList  instance  method  is  called  to  add  a item  type  to  an  object's  in-use  list. 


Parameters 

self  (WPObject  *)  - input 
The  pointer  to  this  object. 
pUseltem  (PUSEITEM)  - input 

A pointer  to  a USEITEM  structure. 


Returns 

Success  indicator: 

TRUE  Successful  completion. 
FALSE  Error  occurred. 


Remarks 

This  method  will  add  a specified  item  type  to  an  object's  in-use  ( USEITEM ) list.  Every  workplace 
object  in  the  system  has  an  in-use  list.  The  in-use  list  is  a linked  list  of  USEITEM  structures  which 
provide  the  object  with  important  information  such  as  the  number  of  container  (WC_CONTAINER) 
windows  it  has  been  inserted  into.  It  also  provides  the  number  of  open  views  (contents,  help,  and 
settings)  of  itself  that  already  exist  and  how  much  memory  it  has  allocated.  The  USEITEM  structure 
consists  of  an  item  type,  a pointer  to  the  next  USEITEM  structure,  and  is  immediately  followed  by  an 
item  type-specific  structure. 


Usage 

The  following  types  of  items  can  be  added  to  the  use  list: 

USAGE_MEMORY  This  item  specifies  a block  of  memory  allocated  for  this  object  through  the 
use  of  the  wpAllocMem  method.  Items  of  this  type  add  a MEMORYITEM 
structure  to  the  end  of  the  USEITEM  structure. 


USAGE_OPENVIEW  When  a view  of  an  object  is  opened,  one  of  these  items  is  added  to  the 

in-use  list.  If  multiple  concurrent  views  are  not  enabled  for  this  object,  the 
USAGE_OPENVIEW  items  are  used  by  the  system  to  automatically  switch  to 
the  open  view  when  the  user  chooses  to  open  the  same  view  again.  This 
behavior  is  controlled  by  the  application  by  calling  the  wpOpen  or  the 
wpSwitchTo  method.  This  item  is  also  used  by  the  system  to  update  the  title 
bar  text  and  switch-entry  text  when  the  user  changes  the  object  title.  If  this 
type  is  specified,  the  in-use  emphasis  bit  will  be  turned  on  for  all  inserted 
records  for  this  object.  Items  of  this  type  concatenate  a VIEWITEM  structure 
to  the  end  of  the  USEITEM  structure. 

USAGE_RECORD  For  every  view  ( WC  CONT AINER)  window  that  the  object  is  inserted  into, 

there  is  one  of  these  items  on  its  in-use  list.  This  enables  an  object  to 
refresh  its  appearance  in  all  views  at  the  same  time.  Items  of  this  type  add 
a RECORDITEM  structure  to  the  end  of  the  USEITEM  structure. 


Chapter  9.  Workplace  Classes,  Instance  Methods,  and  Class  Methods  9-95 


wpAddToObjUseList  - 
WPObject  instance  method 

How  to  Override 

This  method  is  generally  not  overridden. 

Related  Methods 

• wpDeleteFromObjllseList 

• wpFindllseltem 

• wpAllocMem 

• wpCIose 
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wpAllocMem  - 
WPObject  instance  method 


#define  INCL_WINWORKPLACE 


PBYTE  wpAllocMem  (WPObject  * self,  ULONG  cbBytes,  BOOL  fReportError) 


The  wpAllocMem  instance  method  is  called  to  allocate  memory  for  use  by  an  object. 


Parameters 

self  (WPObject  *)  - input 

The  pointer  to  this  object. 

cbBytes  (ULONG)  - input 

Specifies  the  size  of  memory  required. 

fReportError  (BOOL)  - input 
Report  error  indicator: 

TRUE  If  an  error  occurs,  the  system  will  display  an  appropriate  message. 

FALSE  The  system  will  not  display  an  error  message. 

Returns 

Success  indicator: 

NULL  Not  enough  memory  available. 

Other  A pointer  to  the  newly  allocated  memory. 

Remarks 

Memory  allocated  by  the  wpAllocMem  method  should  be  deallocated  when  it  is  no  longer  needed  by 
calling  the  wpFreeMem  method.  Allocated  memory  not  cleaned  up  by  an  object  is  deallocated 
automatically  when  the  object  is  no  longer  in  use. 

Usage 

This  method  can  be  called  at  any  time  to  allocate  memory  to  be  used  for  this  object  only. 

How  to  Override 

This  method  should  be  overridden  if  a substitute  memory  allocation  facility  is  to  be  used.  Object 
classes  overriding  this  method  should  also  override  the  wpFreeMem  method. 

Related  Methods 

• wpFreeMem 
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wpCIose  - 

WPObject  instance  method 


#define  INCL.WINWORKPLACE 


BOOL  wpCIose  (WPObject  * self) 


The  wpCIose  instance  method  is  called  to  close  all  open  views  of  an  object. 


Parameters 

self  (WPObject  *)  - input 
The  pointer  to  this  object. 


Returns 

Success  indicator: 

TRUE  Successful  completion. 

FALSE  Error  occurred. 

Remarks 

This  method  will  cycle  through  the  object's  in-use  list  that  was  created  by  calls  to  the 
wpAddToObjUseList  method.  All  open  windows  specified  by  USAGE_OPENVIEW  items  will  be  sent  a 
WM  CLOSE  message.  Running  executables  specified  by  USAGEjOPENVIEW  items  will  be 
terminated. 


Usage 

This  method  should  be  called  to  close  all  open  views  of  the  object  and  to  free  all  allocated  resources. 


How  to  Override 

If  this  function  is  overridden,  it  should  call  the  parent  last  to  ensure  that  allocated  resources  are 
properly  deallocated. 


Related  Methods 

• wpAddToObjUseList 

• wpDeleteFromObjUseList 

• wpFindUseltem 

• wpOpen 


9-98  PM  Programming  Reference 


wpCnrlnsertObject  - 
WPObject  instance  method 


#define  INCL_WINWORKPLACE 


PMINIRECORDCORE  wpCnrlnsertObject  (WPObject  * self,  HWND  hwndCnr,  PPOINTL  plcon, 

PMINIRECORDCORE  pParent, 

PRECORDINSERT  pRecInsert) 


The  wpCnrlnsertObject  instance  method  is  called  to  insert  a record  into  a container  control  window. 


Parameters 

self  (WPObject  *)  - input 
The  pointer  to  this  object. 
hwndCnr  (HWND)  - input 

The  handle  of  container  control  window, 
plcon  (PPOINTL)  - input 

The  initial  icon  position  in  the  container  control  window. 
pParent  (PMINIRECORDCORE)  - input 

A pointer  to  the  parent  record.  pParent  specifies  the  record  of  the  immediate  parent  of  the 
record  specified  by  plcon.  This  parameter  should  be  set  to  NULL  if  the  record  has  no  parent  or  if 
tree  view  is  not  supported. 

pRecInsert  (PRECORDINSERT)  - input 
Record  position: 

NULL  Insert  the  record  into  the  next  available  position. 

Other  Insert  the  record  into  this  position  specified  by  pRecInsert. 

Returns 

Success  indicator: 

NULL  Error  occurred. 

Other  A pointer  to  the  inserted  record. 

Remarks 

This  method  will  put  an  object  into  a container  control  window  (WC_CONTAINER).  These  container 
windows  can  be  application  created  or  can  be  created  by  the  system  such  as  those  in  folders  and 
settings  notebooks. 

The  OBJECT_FROM_PREC  (prec)  macro  can  be  used  to  determine  the  pointer  to  the  object 
(WPObject  *)  that  is  associated  with  a given  MINIRECORDCORE.prec,  that  was  inserted  using  the 
wpCnrlnsertObject  method. 

The  USER_FROM_PREC(prec)  macro  can  be  used  to  access  the  application  definable  32-bitfield 
within  the  MINIRECORDCORE  structure  that  is  created  when  an  object  is  put  into  a list  control  using 
the  wpCnrlnsertObject  method. 

A record  inserted  by  this  method  will  be  added  to  the  in-use  list.  See  wpAddToObjUseList  for  more 
information  on  an  object's  in-use  list.  wpCnrRemoveObject  should  be  called  to  remove  each  record 
before  the  container  window  is  destroyed. 
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wpCnrlnsertObject  - 
WPObject  instance  method 


Usage 

This  method  is  used  to  give  workplace  object  behavior  (such  as  context  menu  support)  to  records 
inserted  directly  into  a WCJCONTAINER  container  control  window.  To  remove  the  record  from  the 
container,  a call  to  the  wpCnrRemoveObject  method  should  be  made. 


How  to  Override 

This  method  is  generally  not  overridden. 


Related  Methods 

• wpAddToObjUseList 

• wpCnrRemoveObject 
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wpCnrRemoveObject  - 
WPObject  instance  method 


#define  INCL_WINWORKPLACE 


BOOL  wpCnrRemoveObject  (WPObject  * self,  HWNO  hwndCnr,  PMINIRECORDCORE  pRecord) 


The  wpCnrRemoveObject  instance  method  is  called  to  remove  a record  from  a container  control 
window. 

Parameters 

self  (WPObject  *)  - input 
The  pointer  to  this  object. 
hwndCnr  (HWND)  - input 

The  handle  of  the  container  control  (WC_CONTAINER)  window. 
pRecord  (PMINIRECORDCORE)  - input 
The  pointer  to  the  record  to  be  removed. 

Returns 

Success  indicator: 

TRUE  Successful  completion. 

FALSE  Error  occurred. 

Remarks 

This  method  causes  the  item  to  be  removed  from  the  in-use  list. 

Usage 

This  method  should  be  called  to  remove  records  inserted  by  a call  to  the  wpCnrlnsertObject  method. 


How  to  Override 

This  method  is  generally  not  overridden. 

Related  Methods 

• wpCnrlnsertObject 

• wpDeleteFromObjUseList 
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wpCnrSetEmphasis  - 
WPObject  instance  method 


#define  INCL_WINWORKPLACE 


BOOL  wpCnrSetEmphasis  (WPObject  * seif,  ULONG  uiEmphasisAttr,  BOOL  fTurnOn) 


The  wpCnrSetEmphasis  instance  method  is  called  to  allow  the  object  to  change  its  visual  emphasis. 

Parameters 

self  (WPObject  *)  - input 
The  pointer  to  this  object. 

uiEmphasisAttr  (ULONG)  - input 

The  CRA_*  flags.  For  a detailed  list,  see  RECORDCORE  on  page  A-110. 
fTurnOn  (BOOL)  - input 

TRUE  Set  the  specified  attribute. 

FALSE  Reset  the  specified  attribute. 

Returns 

Success  indicator: 

TRUE  Successful  completion 
FALSE  Error  occurred. 

Remarks 

This  method  changes  all  visual  references  to  this  object  to  show  it  with  the  specified  emphasis 
attributes.  This  method  is  called  automatically  to  set  and  reset  CRAJNUSE  emphasis  state  during 
the  processing  of  the  wpAddToObjUseList  and  wpDeleteFromObjUseList  methods,  respectively.  This 
method  is  only  valid  for  objects  inserted  into  a container  control  using  the  wpCnrlnsertObject 
method. 

Usage 

This  method  can  be  called  at  any  time  in  order  to  set  the  emphasis  for  an  object  in  an  open  folder. 
Some  restrictions  apply  as  to  which  CRA_*  can  be  used.  See  RECORDCORE  on  page  A-110.  for 
more  information. 

How  to  Override 

This  method  is  generally  not  overridden. 


Related  Methods 

• wpAddToObjUseList 

• wpCnrlnsertObject 

• wpOpen 
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wpConfirmDelete  - 
WPObject  instance  method 


#define  INCL_WINWORKPLACE 


ULONG  wpConfirmDelete  (WPObject  * self,  ULONG  fConfirmatlons) 


The  wpConfirmDelete  instance  method  is  called  to  allow  the  object  to  prompt  the  user  to  confirm  the 
deletion  of  this  object. 


Parameters 

self  (WPObject  *)  - input 

The  pointer  to  this  object. 

fConfirmatlons  (ULONG)  - input 
The  confirmation  flags. 

CONFIRM_DELETE  Confirm  for  delete  of  all  objects. 
CONFIRM_DELETEFOLDER  Confirm  for  delete  of  folder  objects  only. 


Returns 

User-response  value. 

The  default  processing  will  return  one  of  the  following. 

OK_DELETE  Delete  of  this  object  is  confirmed. 

NO_DELETE  Delete  of  this  object  only  is  cancelled. 

CANCEL  DELETE  Deletion  process  from  that  point  on  is  cancelled. 

Remarks 

This  method  is  called  during  the  processing  of  the  wpDelete  method  only  if  the  system  confirm  on 
delete  flag  is  set. 

Usage 

This  method  is  generally  only  called  by  the  system. 


How  to  Override 

This  method  should  be  overridden  in  order  to  remove  or  replace  the  user  prompt  to  confirm  the 
delete  operation. 


Related  Methods 

• wpDelete 

• wpFree 


Chapter  9.  Workplace  Classes,  Instance  Methods,  and  Class  Methods 


9-103 


wpCopiedFromTemplate  - 
WPObject  instance  method 


#define  INCL_WINWORKPLACE 


VOID  wpCopiedFromTemplate  (WPObject  * self) 


The  wpCopiedFromTemplate  instance  method  is  called  to  allow  an  object  to  perform  class  specific 
processing  when  a new  object  is  created  from  a template. 

Parameters 

self  (WPObject  *)  - input 
The  pointer  to  this  object. 


Returns 

The  return  value  is  VOID. 

Remarks 

This  method  is  called  immediately  after  a new  object  is  created  from  a template.  The  system  does 
not  do  any  default  processing  for  this  method.  This  method  is  typically  overridden  to  perform  class 
specific  initialization  on  a created  object.  For  example,  a customer  order  form  class  would  prefill  the 
date,  time,  and  order  number  in  an  instance  of  itself  that  was  created  from  a template. 

Usage 

This  method  is  generally  only  called  by  the  system. 


How  to  Override 

This  method  should  be  overridden  by  object  classes  which  need  to  initialize  the  new  object  after  it  is 
created  from  a template. 
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wpCopyObject  - 
WPObject  instance  method 


#define  INCL_WINWORKPLACE 


WPObject  * wpCopyObject  (WPObject  * self,  WPFolder  * Folder,  BOOL  fLock) 


The  wpCopyObject  instance  method  is  called  to  create  a new  copy  of  the  object. 

Parameters 

self  (WPObject  *)  - input 
The  pointer  to  this  object. 

Folder  (WPFolder  *)  - input 

A pointer  to  a Folder  object  in  which  to  place  this  new  object.  This  pointer  can  be  determined  by 
issuing  a call  to  the  wpcisQueryFolder  method. 

fLock  (BOOL)  - input 
The  lock  object  flag. 

If  this  flag  is  false,  the  newly  created  object  will  be  made  dormant  whenever  the  object  and  the 
folder  containing  the  object  are  closed.  If  this  flag  is  true,  the  new  object  will  remain  active  until 
the  caller  issues  the  wpUnlockObject  method  on  it. 

Returns 

Success  indicator: 

NULL  Error  occurred. 

Other  A pointer  to  the  new  object  created. 

Remarks 

Copies  of  an  object  can  always  be  deleted  and  moved  by  default,  even  if  the  original  has  the 
OBJSTYLE_NODELETE  or  OBJSTYLE_NOMOVE  style  set. 

Usage 

This  method  can  be  called  any  time  in  order  to  create  a copy  of  an  existing  object. 

How  to  Override 

This  method  can  be  overridden  by  classes  which  need  to  keep  track  of  where  instances  are. 
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wpCreateFromTemplate  - 
WPObject  instance  method 


#define  INCL_WINWORKPLACE 


WPObject  * wpCreateFromTemplate  (WPObject  * self,  WPFolder  * Folder,  BOOL  fLock) 


The  wpCreateFromTemplate  instance  method  is  called  to  create  an  object  from  a template. 


Parameters 

self  (WPObject  *)  - input 
The  pointer  to  this  object. 

Folder  (WPFolder  *)  - input 

A pointer  to  a folder  object  in  which  to  place  the  new  object.  This  pointer  can  be  determined  by 
issuing  a call  to  the  wpcisQueryFolder  method. 

fLock  (BOOL)  - input 
The  lock  object  flag. 

If  this  flag  is  false,  the  newly  created  object  will  be  made  dormant  whenever  the  object  and  the 
folder  containing  the  object  are  closed.  If  this  flag  is  true,  the  new  flag  will  remain  active  until 
the  caller  issues  the  wpUnlockObject  method  on  it. 


Returns 

Success  indicator: 

NULL  Error  occurred. 

Other  Pointer  to  the  new  object. 

Remarks 

The  new  object  will  be  an  identical  copy  of  the  template  object  with  the  exception  that  the 
OBJSTYLE_TEMPLATE  object  style  will  be  taken  out.  wpCopiedFromTemplate  instance  method  will 
be  called  on  the  new  object. 

Usage 

This  method  can  be  called  at  any  time  in  order  to  create  a new  object  from  a template  object. 

How  to  Override 

This  method  is  generally  not  overridden. 

Related  Methods 

• wpCopyObject 

• wpcisNew 
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wpCreateShadowObject  - 
WPObject  instance  method 


#define  INCL_WINWORKPLACE 


WPObject  * wpCreateShadowObject  (WPObject  * self,  WPFolder  * Folder,  BOOL  fLock) 


The  wpCreateShadowObject  instance  method  is  called  to  create  a shadow  of  an  object. 

Parameters 

self  (WPObject  *)  - input 
The  pointer  to  this  object. 

Folder  (WPFolder  *)  - input 

A pointer  to  a folder  object  in  which  to  place  the  new  shadow  object.  This  pointer  can  be 
determined  by  issuing  a call  to  the  wpcisQueryFolder  method. 

fLock  (BOOL)  - input 
Lock  object  flag. 

If  this  flag  is  false,  the  new  shadow  object  will  be  made  dormant  whenever  the  object  and  the 
folder  containing  the  object  are  closed. 

If  this  flag  is  true,  the  new  object  will  remain  awake  until  the  caller  issues  the  wpUnlockObject 
method  on  it. 

Returns 

Success  indicator: 

NULL  Error  occurred. 

OTHER  Pointer  to  the  new  shadow  object. 

Remarks 

The  new  object  is  created  as  an  instance  of  class  WPShadow. 

Usage 

This  method  can  be  called  at  any  time  in  order  to  create  a shadow  object  for  this  object. 

How  to  Override 

This  method  is  generally  not  overridden. 
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wpDelete  - 

WPObject  instance  method 


#define  INCL_WINWORKPLACE 


ULONG  wpDelete  (WPObject  * self,  ULONG  ^Confirmations) 


The  wpDelete  instance  method  is  called  to  delete  an  object  and  prompt  for  confirmation  if  necessary. 


Parameters 

self  (WPObject  *)  - input 
The  pointer  to  the  object. 


Prompt  for  confirmation  for  all  objects. 

Prompt  for  confirmation  for  just  folder  objects. 
No  confirmations. 


(■■Confirmations  (ULONG)  - input 

The  confirmation  flags: 

CONFIRM_DELETE 

CONFIRMDELETEFOLDER 

NULL 


Returns 

Success  indicator: 

NO_DELETE  Error  occurred. 

CANCEL  DELETE  User  canceled  operation. 

OK_DELETE  Object  was  deleted. 

Remarks 

The  confirmation  flags  are  passed  to  the  wpConfirmDelete  method.  If  wpConfirmDelete  returns 
OK_DELETE,  the  wpFree  method  is  called  on  the  object. 

Usage 

This  method  can  be  called  at  any  time  in  order  to  delete  an  object. 


How  to  Override 

This  method  is  generally  not  overridden. 


Related  Methods 

• wpFree 

• wpConfirmDelete 

• wpQueryConfirmations 
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wpDeleteAlEJobs  - 
WPPrinter  instance  method 


#define  INCL_WINWORKPLACE 


BOOL  wpDeleieAHJobs  (WPPrinter  * self) 


The  wpDeleteAMJobs  instance  method  is  called  to  delete  all  jobs  in  a printer  (print  destination) 
object. 

Parameters 

self  (WPPrinter  *)  - input 

The  pointer  to  the  object  to  delete  all  jobs. 

Returns 

Success  indicator: 

TRUE  Successful  completion 
FALSE  Error  occurred. 

How  to  Override 

This  method  is  generally  not  overridden. 

Related  Methods 

• wpDeleteJob 
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wpDeleteContents  - 
WPFolder  instance  method 


#define  INCL_WINWORKPLACE 


ULONG  wpDeleteContents  (WPFolder  * self,  ULONG  u (Confirmations) 


The  wpDeleteContents  instance  method  is  called  to  delete  the  contents  of  a folder. 

Parameters 

self  (WPFolder  *)  - input 

The  pointer  to  the  object. 

ulConfirmations  (ULONG)  - input 
The  confirmation  flags: 

CONFIRM_DELETE 

CONFIRMDELETEFOLDER 

NULL 

Returns 

Success  indicator. 

OK_DELETE  All  objects  were  deleted. 

NO_DELETE  Error  occurred.  At  least  one  object  was  not  deleted. 

CANCEL  DELETE  User  canceled  operation. 

Remarks 

wpDelete  and  wpFree  will  automatically  call  this  instance  method  for  folder  objects. 

Usage 

This  method  can  be  called  at  any  time  to  delete  the  contents  of  a folder. 

How  to  Override 

This  method  is  generally  not  overridden. 

Related  Methods 

• wpFree 

• wpDelete 


Prompt  for  confirmation  for  all  objects. 

Prompt  for  confirmation  for  just  folder  objects. 
No  confirmations. 
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wpDeleteFromObjUseList  - 
WPObject  instance  method 


#define  INCL_WINWORKPLACE 


BOOL  wpDeleteFromObjUseList  (WPObject  * self,  PUSEITEM  pUseltem) 


The  wpDeleteFromObjUseList  instance  method  is  called  to  remove  an  item  type  from  an  object's 
in-use  list. 


Parameters 

self  (WPObject  *)  - input 
The  pointer  to  this  object. 
pUseltem  (PUSEITEM)  - input 

A pointer  to  a USEITEM  structure. 

Returns 

Success  indicator: 

TRUE  Successful  completion. 

FALSE  Error  occurred. 

Remarks 

This  method  will  remove  a specified  item  type  from  an  object's  in-use  (USEITEM)  list. 

If  the  usage  item  being  removed  is  of  type  USAGE_OPENVIEW,  the  in-use  emphasis  bit  will  be  turned 
off  for  all  inserted  records  for  this  object. 

Usage 

A call  to  this  method  should  be  made  when  a particular  usage  item,  added  to  the  in-use  list  via  the 
wpAddToObjUseList  method,  is  no  longer  needed. 

This  method  must  be  called  before  the  USEITEM  memory  is  freed. 

How  to  Override 

This  method  is  generally  not  overridden. 

Related  Methods 

• wpAddToObjUseList 

• wpFindUseltem 
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wpDeleteJob  - 
WPJob  instance  method 


#define  INCL_WINWORKPLACE 


BOOL  wpDeleteJob  (WPJob  * self) 


The  wpDeleteJob  instance  method  is  called  to  delete  a job  object. 

Parameters 

self  (WPJob  *)  - input 

The  pointer  to  the  object  to  be  deleted. 

Returns 

Success  indicator: 

TRUE  Successful  completion 
FALSE  Error  occurred. 

How  to  Override 

This  method  is  generally  not  overridden. 

Related  Methods 

• wpDeleteAllJobs 
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wpDisplayHelp  - 
WPObject  instance  method 


#define  INCL_WINWORKPLACE 


BOOL  wpDisplayHelp  (WPObject  * self,  ULONG  ulHelpPanelld,  PSZ  pszHelpLIbrary) 


The  wpDisplayHelp  instance  method  is  called  to  allow  the  object  to  display  a help  panel. 


Parameters 

self  (WPObject  *)  - input 
The  pointer  to  this  object. 
ulHelpPanelld  (ULONG)  - input 
The  object's  help  panel  id. 
pszHelpLIbrary  (PSZ)  - input 

A pointer  to  a zero  terminated  string  which  contains  the  name  of  the  help  library. 


Returns 

Success  indicator: 

TRUE  Successful  completion 
FALSE  Error  occurred. 

Remarks 

This  method  allows  each  object  class  to  display  a help  panel  in  response  to  a users  request  for  help. 
The  help  panel  will  be  displayed  by  the  shell  on  a help  instance  managed  by  the  shell. 

Usage 

This  method  can  be  called  at  any  time  in  order  to  display  a help  panel. 

How  to  Override 

This  method  is  generally  not  overridden. 


Related  Methods 

• wpMenultemHelpSelected 

• wpQueryDefaultHelp 

• wpSetDefaultHelp 

• wpcIsQueryDefaultHelp 
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wpDoesObjectMatch  - 
WPObject  instance  method 


#define  INCL_WINWORKPLACE 


BOOL  wpDoesObjectMatch  (WPObject  * object,  PVOID  pExtendedCriterla) 


The  wpDoesObjectMatch  instance  method  is  called  to  allow  the  object  to  determine  if  it  matches  the 
specified  criteria. 

Parameters 

object  (WPObject  *)  - input 

The  pointer  to  the  object  to  be  examined. 

pExtendedCriterla  (PVOID)  - input 

A pointer  to  a buffer  that  contains  the  class-specific  extended  search  criteria. 


Returns 

Success  indicator: 

TRUE  The  object  matches  the  specified  criteria. 

FALSE  The  object  does  not  match  the  specified  criteria. 

Remarks 

If  the  object  class  has  extended  search  criteria,  this  method  gets  called  to  determine  if  the  object 
found,  matches  the  extended  search  criteria. 

Usage 

This  method  can  be  called  at  any  time  in  order  to  determine  if  an  object  matches  some  extended 
search  criteria. 

How  to  Override 

This  method  should  be  overridden  by  classes  which  introduce  extended  search  criteria  for  use  by  the 
Find  and  Include  facilities. 
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wpDragCell  - 
WPPalette  instance  method 


#define  INCL_WINWORKPLACE 


BOOL  wpDragCell  (WPPalette  * self,  PCELL  pCell,  HWND  hwndPal,  PPOINTL  pptIDrag) 


The  wpDragCell  instance  method  is  called  to  drag-apply  a value  in  a cell. 

Parameters 

self  (WPPalette  *)  - input 
The  pointer  to  the  object. 
pCell  (PCELL)  - input 

A pointer  to  the  CELL  structure  to  be  dragged. 
hwndPal  (HWND)  - input 

The  palette  window  handle. 
pptIDrag  (PPOINTL)  - input 

The  point  in  hwndPal  coordinates  from  which  drag  was  initiated. 

Returns 

Success  indicator. 

TRUE  Successful  completion. 

FALSE  Error  occurred. 

Remarks 

The  default  processing  for  this  method  by  the  WPPalette  class  is  to  do  nothing  other  than  return 
FALSE. 

Usage 

This  method  is  generally  called  only  by  the  palette  window  after  it  receives  the  WM_BEGINDRAG 
message. 

How  to  Override 

This  method  should  be  overridden  to  handle  the  drag-apply  action. 

Override  processing  should  include  capturing  the  mouse  and,  waiting  for  and  processing  the 
WM_ENDDRAG  message 
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wpDraggedOverObject  - 
WPObject  instance  method 


#define  INCL_WINWORKPLACE 


M RESULT  wpDraggedOverObject  (WPObject  * somSelf,  WPObject  * DraggedOverObject) 


The  wpDraggedOverObject  instance  method  may  be  called  on  an  object  that  is  currently  being 
dragged  with  the  mouse  to  tell  it  what  the  current  target  object  is.  The  return  code  from  this  method 
lets  the  system  know  whether  the  object  being  dragged  can  be  dropped  on  the  specified  target. 

Parameters 

somSelf  (WPObject  *)  - input 

The  pointer  to  an  object  being  dragged. 

DraggedOverObject  (WPObject  *)  - input 

Pointer  to  the  object  that  the  drag  cursor  is  over,  the  current  target  object  for  the  drag  operation. 


Returns 

LowWord  Droplndicator  (USHORT). 

This  code  is  one  of  the  DOR_  constants,  such  as  DOR_DROP  or  DOR_NODROP 
which  indicate  whether  a drop  is  allowed  on  the  current  target. 

HighWord  DropOperation  (USHORT). 

The  current  drag  operation  code.  Examples  are  DO_COPY,  DO_MOVE  or  DOJJNK 
to  indicate  that  the  drag  action  over  this  target  should  be  a copy,  move  or  a link. 


Remarks 

When  a target  object  is  dragged  over  by  the  mouse,  it  will  always  receive  a wpDragOver  instance 
method  call.  Many  target  objects  will  choose  to  decide  the  current  drag  operation  and  whether  a 
drop  is  possible  based  upon  their  own  rules.  For  instance,  the  WPShredder  object  will  return 
DO_DROP,DO_MOVE  if  it  decides  that  all  the  source  objects  can  be  deleted.  However,  some  targets 
require  the  source  or  sources  to  participate  in  the  decision  over  whether  they  can  accept  the  drop. 
The  way  that  a target  allows  a source  object  to  have  a say  in  what  the  drop  action  will  be  is  by 
calling  the  wpDraggedOverObject  on  each  source  object.  The  wpDraggedOverObject  instance 
method  may  be  invoked  on  an  object  that  is  being  dragged  (source  object)  at  any  time,  to  see  if  it  can 
support  a drop  on  the  current  target.  If  the  object  that  is  being  dragged  responds  favorably  to  this 
method,  it  may  later  receive  a wpDroppedOnObject  instance  method  call  so  that  it  can  process  the 
drop  action. 

As  an  example,  consider  the  case  where  a program  object  is  dragged  onto  a data  file  object.  The 
program  would  respond  DO_DROP  to  the  wpDraggedOverObject  instance  method,  so  that  the  data 
file  would  be  a valid  drop  target.  If  the  user  chose  to  allow  the  drop,  then  the  program  will  receive  a 
wpDroppedOnObject  instance  method  at  which  time  it  would  be  able  to  open  itself  as  a viewer  of  the 
data  file  object. 

This  method  is  called  as  a result  of  a DMDRAGOVER  message  being  sent,  and  for  further 
documentation  of  the  possible  return  values,  see  “DM  DRAGOVER”  on  page  29-4. 
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wpDraggedOverObject  - 
WPObject  instance  method 


Usage 

This  method  is  typically  called  by  objects  that  require  participation  from  the  source  object  when  a 
drop  occurs.  The  method  can  be  called  at  any  time,  however  the  method  would  normally  only  be 
called  by  a target  object  on  one  of  the  source  objects  during  a drag  or  drop  operation. 


How  to  Override 

Override  this  method  if  your  object  class  wishes  to  allow  itself  to  be  used  as  a source  object  that  can 
perform  a drop  operation.  A favorable  return  code  from  this  method  may  lead  to  a 
wpDroppedOnObject  instance  method  being  invoked  on  the  source  object  which  would  be  overridden 
to  actually  do  the  drop  operation. 

Related  Methods 

• wpDragOver 

• wpDrop 

• wpDroppedOnObject 

• wpFormatDragltem 
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wpDragOver  - 
WPObject  instance  method 


#define  INCL_WINWORKPLACE 


MRESULT  wpDragOver  (WPObject  * self,  HWND  hwndCnr,  PDRAGINFO  pDraglnfo) 


The  wpDragOver  instance  method  is  called  to  inform  the  object  that  other  objects  are  being  dragged 
over  it. 


Parameters 

self  (WPObject  *)  - input 
The  pointer  to  this  object. 
hwndCnr  (HWND)  - input 

The  handle  to  the  container  control  window. 
pDraglnfo  (PDRAGINFO)  - input 
A pointer  to  drag  information. 


Returns 

See  “DM_DRAGOVER”  on  page  29-4  for  description  of  the  return  value. 

Remarks 

The  wpDragOver  method  is  sent  for  each  DM_DRAGOVER  message  received  by  the  object.  See 
"DM_DRAGOVER”  on  page  29-4  for  more  information. 

Usage 

This  method  is  generally  only  called  by  the  system  as  the  folder  containing  the  object  processes  the 
DM  DRAGOVER  message. 


How  to  Override 

This  method  should  be  overridden  to  determine  if  the  object  or  objects  being  dragged  can  be 
dropped  on  this  object. 


Related  Methods 

• wpDrop 

• wpFormatDragltem 


9-118  PM  Programming  Reference 


wpDrop  - 

WPObject  instance  method 


#define  INCL_WINWORKPLACE 


MRESULT  wpDrop  (WPObject  * self,  HWND  hwndCnr,  PDRAGINFO  pDraglnfo, 
PDRAGITEM  pDragltem) 


The  wpDrop  instance  method  is  called  to  inform  an  object  that  another  object  has  been  dropped  on  it. 


Parameters 

self  (WPObject  *)  - input 
The  pointer  to  this  object. 
hwndCnr  (HWND)  - input 

The  handle  to  the  container  control  window. 
pDraglnfo  (PDRAGINFO)  - input 

A pointer  to  a PDRAGINFO  structure. 
pDragltem  (PDRAGITEM)  - input 

A pointer  to  a PDRAGITEM  structure. 


Returns 

See  "DM_DROP”  on  page  29-6  for  description  of  the  return  value. 


Remarks 

The  wpDrop  method  is  called  when  a DM  DROP  message  is  received  by  the  object.  See 
“DM_DROP”  on  page  29-6  for  more  information. 

Usage 

This  method  is  generally  only  called  by  the  system  as  a folder  containing  the  object  processed  the 
DM  DROP  message. 


How  to  Override 

This  method  should  be  overridden  to  process  the  action  of  the  dragged  object  or  objects  being 
dropped  on  it. 


Related  Methods 

• wpDragOver 

• wpFormatDragltem 
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wpDroppedOnObject  - 
WPObject  instance  method 


#define  INCL_WINWORKPLACE 


BOOL  wpDroppedOnObject  (WPObject  * somSelf,  WPObject  * DroppedOnObject) 


The  wpDroppedOnObject  instance  method  is  called  on  an  object  that  has  just  been  dragged  (a 
source  object)  when  the  target  object  that  it  was  dropped  on  does  not  know  what  action  to  perform. 
This  instance  method  is  only  called  on  a source  object  when  that  source  object  has  previously 
responded  favorably  to  a wpDraggedOverObject  instance  method  call. 


Parameters 

somSelf  (WPObject  *)  - input 

The  pointer  to  an  object  being  dragged. 

DroppedOnObject  (WPObject  *)  - input 

Pointer  to  the  object  that  was  dropped  on.  The  current  target  object  for  the  drag  operation. 


Returns 

TRUE  The  drop  action  was  successful. 

FALSE  An  error  occurred. 

Remarks 

When  you  drop  on  an  a target  object  and  the  source  object  has  said  it  knows  how  to  handle  the  drop 
operation,  this  method  will  be  invoked  on  the  source  object.  For  example,  the  program  object  class 
supports  being  dropped  on  certain  other  classes  of  object  where  the  drop  action  will  be  taken  by  the 
program  itself.  The  drop  action  provided  in  WPProgram's  override  of  the  wpDroppedOnObject 
method  would  be  to  execute  itself  as  a viewer  of  the  target  object.  This  method  is  called  as  a result 
of  a DMDROP  message  being  sent. 

Usage 

Target  objects  that  do  not  know  how  to  handle  the  current  drop  operation  can  call  this  method  on  the 
source  object  that  was  dropped  on  it.  This  method  would  not  normally  be  called  outside  the  scope  of 
a drag  or  drop  operation. 


How  to  Override 

Object  classes  that  override  the  wpDraggedOverObject  instance  method  would  normally  be  expected 
to  also  override  this  method. 

Related  Methods 

• wpDragOver 

• wpDraggedOverObject 

• wpDrop 

• wpFormatDragltem 
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wpEditCell  - 
WPPalette  instance  method 


#define  INCL_WINWORKPLACE 


BOOL  wpEditCell  (WPPalette  * self,  PCELL  pCell,  HWND  hwndPal) 


The  wpEditCell  instance  method  is  called  to  edit  a value  in  a cell. 

Parameters 

self  (WPPalette  *)  - input 
The  pointer  to  the  object. 
pCell  (PCELL)  - input 

A pointer  to  the  CELL  structure  to  be  edited. 
hwndPal  (HWND)  - input 

The  palette  window  handle. 

Returns 

Success  indicator. 

TRUE  Successful  completion. 

FALSE  Error  occurred. 

Remarks 

The  default  processing  for  this  method  by  the  WPPalette  class  is  to  do  nothing  other  than  return 
FALSE. 

Usage 

This  method  is  generally  called  only  by  the  palette  window  when  the  user  requests  to  edit  the  value 
in  the  cell.  This  request  is  made  by  selecting  a cell  and  pressing  the  Enter  key  or  the  edit 
pushbutton,  or  by  double-clicking  on  the  cell. 

How  to  Override 

This  method  should  be  overridden  to  handle  the  edit  action. 
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wpEndConversation  - 
WPObject  instance  method 


#define  INCL_WINWORKPLACE 


M RESULT  wpEndConversation  (WPObject  * self,  ULONG  ulltemld,  ULONG  uiResult) 


The  wpEndConversation  instance  method  is  called  to  notify  the  object  that  the  drag  or  drop  operation 
is  complete. 

Parameters 

self  (WPObject  *)  - input 
The  pointer  to  the  object, 
ulltemld  (ULONG)  - input 

This  is  the  ulltemID  from  the  DRAGITEM  that  was  contained  within  the  DRAGINFO  structure 
when  the  object  was  dropped. 

uiResult  (ULONG)  - input 

Flag  indicating  whether  the  operation  was  performed  successfully.  See 
“DM_ENDCONVERSATION”  on  page  29-8  for  more  information  about  this  parameter. 

Returns 

Refer  to  the  DM  ENDCONVERSATION  message  for  a description  of  the  return  value. 


Remarks 

The  wpEndConversation  method  is  called  when  the  object  receives  a DM_ENDCONVERSATION 
message.  Refer  to  the  DM_ENDCONVERSATION  message  for  more  information. 

Usage 

This  method  is  generally  called  only  by  the  system  as  the  folder  containing  the  object  processed  by 
the  DM_ENDCONVERSATION  message. 


How  to  Override 

This  method  should  be  overridden,  if  the  object  needs  to  do  any  actions  once  the  drag  or  drop 
operation  is  complete. 


Related  Methods 

• wpDragOver 

• wpDrop 

• wpFormatDragltem 

• wpRender 

• wpRenderComplete 
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wpFilterPopupMenu  - 
WPObject  instance  method 


#define  INCL_WINWORKPLACE 


ULONG  wpFilterPopupMenu  (WPObject  * self,  ULONG  ulFlags,  HWND  hwndcnr, 

BOOL  fMultiSelect) 


The  wpFilterPopupMenu  instance  method  is  called  to  allow  the  object  to  modify  its  context  menu. 


Parameters 

self  (WPObject  *)  - input 
The  pointer  to  this  object. 
ulFlags  (ULONG)  - input 

If  the  flag  is  set,  the  corresponding  pop-up  menu  item  will  be  available.  These  flags  are  o red 
together  with  the  flags  already  defined  by  ancestor  classes,  to  specify  the  standard  pop-up  menu 
items  which  apply  to  this  object. 

Create  another 
Open 
Switch  to 
Close 

Open  settings 
Print 
Help 
Delete 
Copy 
Move 

Create  shadow 
Window 

hwndcnr  (HWND)  - input 

The  handle  to  container  control  window. 
fMultiSelect  (BOOL)  - input 

The  multiple  menu  items  flag. 


Returns 

New  pop-up  menu  flags  for  this  object. 


CTXT_NEW 

CTXT_OPEN 

CTXT_SWITCHTO 

CTXT_CLOSE 

CTXT_SETTINGS 

CTXT_PRINT 

CTXT_HELP 

CTXT_DELETE 

CTXT_COPY 

CTXT_MOVE 

CTXT_LINK 

CTXT  WINDOW 
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wpFilterPopupMenu  - 
WPObject  instance  method 


Usage 

This  method  is  generally  only  called  by  the  system  when  a request  is  made  to  display  the  object's 
pop-up  window. 


How  to  Override 

This  method  should  be  overridden  to  remove  undesired  pop-up  menu  actions  that  were  added  by 
ancestor  classes.  The  parent  method  should  be  called  prior  to  any  override  processing. 


Related  Methods 

• wpMenultemSelected 

• wpMenultemHelpSelected 

• wpModifyPopupMenu 

• wpinsertPopupMenultems 
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wpFindUseltem  - 
WPObject  instance  method 


#define  INCL_WINWORKPLACE 


PUSEITEM  wpFindUseltem  (WPObject  * self,  ULONG  ultype,  PUSEITEM  pCurrentUseltem) 


The  wpFindUseltem  instance  method  is  called  to  retrieve  an  item  type  from  the  object's  in-use  list. 


Parameters 

self  (WPObject  *)  - input 

The  pointer  to  this  object. 

ultype  (ULONG)  - input 

Specify  the  usage  type  of  the  item  to  be  located. 

pCurrentUseltem  (PUSEITEM)  - input 
A pointer  to  a USEITEM  structure: 

NULL  Retrieve  the  first  item  in  the  in-use  list  that  has  a usage  type  of  ultype. 

Other  Retrieve  the  next  item  in  the  in-use  list,  following  the  item  specified  by 
pCurrentUseltem,  that  has  a usage  type  of  ultype. 

Returns 

Success  indicator: 

NULL  No  items  matching  the  specified  find  criteria  were  found  in  the  i n-use  I ist  for  this  object. 
Other  A pointer  to  a USEITEM  structure  that  matches  the  specified  find  criteria. 

Remarks 

This  method  will  search  the  object's  in-use  list  for  all  items  that  were  added  by  previous  calls  to  the 
wpAddToObjUseList  method. 

Usage 

This  method  should  be  called  to  determine  how  the  object  is  currently  being  used,  for  example, 
which  views  are  currently  open  and  what  container  window  it  is  inserted  into. 


How  to  Override 

This  method  is  generally  not  overridden. 


Related  Methods 

• wpAddToObjUseList 

• wpDeleteFromObjUseList 
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wpFormatDragltem  - 
WPObject  instance  method 


#define  INCL_WINWORKPLACE 


BOOL  wpFormatDragltem  (WPObject  * self,  PDRAGITEM  pDragltem) 


The  wpFormatDragltem  instance  method  is  called  to  allow  the  object  to  format  its  drag  information 
when  the  user  starts  to  drag  it. 


Parameters 

self  (WPObject  *)  - input 
The  pointer  to  this  object. 
pDragltem  (PDRAGITEM)  - input 
The  address  of  the  drag  item. 

Returns 

Success  indicator: 

TRUE  Successful  completion 
FALSE  Error  occurred. 

Remarks 

This  method  will  enable  the  direct  manipulation  of  this  object  by  initializing  the  DRAGITEM  structure. 

Usage 

This  method  is  generally  only  called  by  the  system  when  the  user  first  starts  to  drag  the  object. 

How  to  Override 

This  method  is  generally  overridden  by  classes  which  require  special  processing  to  initiate  a drag  or 
drop  operation. 

Related  Methods 

• wpDragOver 

• wpDrop 
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wpFree  - 

WPObject  instance  method 


#define  INCL_WINWORKPLACE 


BOOL  wpFree  (WPObject  * self) 


The  wpFree  instance  method  is  called  to  destroy  the  object  and  deallocate  its  associated  resources. 

Parameters 

self  (WPObject  *)  - input 
The  pointer  to  this  object. 


Returns 

Success  indicator: 

True  Successful  completion 
False  Error  occurred. 

Remarks 

This  method  destroys  the  persistent  form  of  the  object  and  then  frees  the  memory  that  represented 
that  object.  If  confirmations  are  on,  wpDelete  will  prompt  the  user  before  calling  wpFree. 

Usage 

General  destruction  of  an  object  should  be  done  with  the  wpDelete  method.  This  method  is  generally 
only  called  by  the  system. 

How  to  Override 

This  method  is  generally  overridden  by  storage  classes  which  permanently  remove  this  object  and 
its  associated  data,  or  any  objects  that  need  to  do  special  processing  before  deletion. 

Related  Methods 

• wpDelete 

• wpUnlnitData 
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wpFreeMem  - 
WPObject  instance  method 


#define  INCL_WINWORKPLACE 


BOOL  wpFreeMem  (WPObject  * self,  PBYTE  pbMemory) 


The  wpFreeMem  instance  method  is  called  to  deallocate  memory  allocated  by  a call  to  the 
wpAllocMem  method. 


Parameters 

self  (WPObject  *)  - input 
The  pointer  to  this  object. 
pbMemory  (PBYTE)  - input 

The  pointer  to  the  memory  to  be  deallocated. 

Returns 

Success  indicator: 

TRUE  Successful  completion 
FALSE  Error  occurred. 

Remarks 

This  method  deallocates  memory  for  an  object.  wpFreeMem  should  always  be  called  when  the 
memory  allocated  by  wpAllocMem  is  no  longer  needed. 

Usage 

This  method  should  be  called  when  the  memory  allocated  by  a call  to  the  wpAllocMem  method  is  no 
longer  needed. 

How  to  Override 

This  method  should  only  be  overriden  to  provide  the  deallocation  of  memory  allocated  by  an 
override  method  of  wpAllocMem. 

Related  Methods 

• wpAllocMem 
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wpHide  - 

WPObject  instance  method 


#define  INCL_WINWORKPLACE 


BOOL  wpHide  (WPObject  * self) 


The  wpHide  instance  method  is  called  to  hide  or  minimize  open  views  of  this  object. 

Parameters 

self  (WPObject  *)  - input 
The  pointer  to  this  object. 


Returns 

Success  indicator: 

True  Successful  completion 
False  Error  occurred. 

Remarks 

This  method  will  turn  all  windows  owned  by  this  object  invisible  or  if  the  system  setting  is  set  to 
provide  minimized  windows  instead  of  hidden  windows,  wpHide  will  minimize  all  windows  owned  by 
this  object. 

Usage 

This  method  can  be  called  to  hide  an  object's  window. 

How  to  Override 

This  method  is  not  generally  overridden. 

Related  Methods 

• wpRestore 
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wpHideFIdrRunObjs  - 
WPFolder  instance  method 


#define  INCL_WINWORKPLACE 


BOOL  wpHideFIdrRunObjs  (WPFolder  * self,  BOOL  (Hide) 


The  wpHideFIdrRunObjs  instance  method  is  called  to  allow  the  folder  to  hide  or  minimize  its  open 
objects. 

Parameters 

self  (WPFolder  *)  - input 
The  pointer  to  this  object. 
fHide  (BOOL)  - input 

Flag  to  indicate  hide  or  show  of  open  objects. 

True  Hide  all  objects  opened  from  this  folder. 

False  Unhide  all  objects  opened  from  this  folder. 

Returns 

Success  indicator: 

True  Successful  completion 
False  Error  occurred. 

Remarks 

Open  objects  in  this  folder  will  either  be  hidden  or  minimized,  depending  on  the  current  system 
setting.  This  method  is  called  automatically  on  folders  with  the  work  area  flag,  FOI_WORKAREA,  set 
when  it  is  hidden  or  minimized. 

Usage 

This  method  can  be  called  at  any  time  in  order  to  hide  or  minimize  all  objects  in  this  folder  which  are 
currently  open. 

How  to  Override 

This  method  is  generally  not  overridden. 
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wpHoIdJob  - 
WPJob  instance  method 


#define  INCL_WINWORKPLACE 


BOOL  wpHoIdJob  (WPJob  * self) 


The  wpHoIdJob  instance  method  is  called  to  hold  a job  object. 

Parameters 

self  (WPJob  *)  - input 

The  pointer  to  the  object  to  be  held. 

Returns 

Success  indicator: 

TRUE  Successful  completion 
FALSE  Error  occurred. 

How  to  Override 

This  method  is  generally  not  overridden. 

Related  Methods 

• wpReleaseJob 


Chapter  9.  Workplace  Classes,  Instance  Methods,  and  Class  Methods 


9-131 


wpHoldPrinter  - 
WPPrinter  instance  method 


#define  INCL_WINWORKPLACE 


BOOL  wpHoldPrinter  (WPPrinter  * self) 


The  wpHoldPrinter  instance  method  is  called  to  hold  a print  object. 

Parameters 

self  (WPPrinter  *)  - input 

The  pointer  to  the  object  to  be  held. 

Returns 

Success  Indicator: 

TRUE  Successful  completion 
FALSE  Error  occurred. 

How  to  Override 

This  method  is  generally  not  overridden. 

Related  Methods 

• wpReleasePrinter 
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wpInitData  - 
WPObject  instance  method 


#define  INCL_WINWORKPLACE 


VOID  wpInitData  (WPObject  * self) 


The  wpInitData  instance  method  is  called  to  allow  the  object  to  initialize  its  instance  data. 

Parameters 

self  (WPObject  *)  - input 
The  pointer  to  this  object. 


Returns 

The  return  value  is  VOID. 

Remarks 

This  routine  is  called  when  the  object  is  created  or  when  it  is  awakened  from  the  dormant  state  so 
that  it  can  initialize  all  of  its  instance  variables  to  a known  state.  Note  that  this  method  is  called 
before  the  object's  state  is  known,  so  it  is  very  important  that  the  object  does  not  try  to  process  any 
other  method  while  processing  this  method.  Should  an  object  require  extra  initialization  that 
requires  it  to  invoke  other  methods,  this  should  be  done  from  the  wpRestoreState  instance  method. 
When  the  object  is  first  created,  the  wpSetup  instance  method  should  be  overridden  to  perform 
initialization  that  is  only  required  once. 

Usage 

This  method  is  generally  only  called  by  the  system  when  the  object  is  awake. 


How  to  Override 

Any  class  that  has  instance  variables  should  override  this  method  so  that  those  variables  are  all 
initially  in  a known  state.  It  is  essential  to  pass  this  method  onto  the  parent  class.  If  this  method  is 
overridden,  the  wpUnlnitData  method  should  also  be  overridden  in  order  to  deallocate  resources  that 
were  allocated  by  the  override  processing  of  wpInitData. 


Related  Methods 

• wpSetup 

• wpUnlnitData 
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wpInsertPopupMenultems 
WPObject  instance  method 


#define  INCL_WINWORKPLACE 


BOOL  wpInsertPopupMenultems  (WPObject  * self,  HWND  hwndMenu,  ULONG  ulPostltlon, 

HMODULE  hmod,  ULONG  ulMenulO,  ULONG  ulSubMenuld) 


The  wpInsertPopupMenultems  instance  method  Is  called  to  allow  an  object  to  Insert  items  into  its 
popup  menu. 


Parameters 

self  (WPObject  *)  - input 
The  pointer  to  this  object. 
hwndMenu  (HWND)  - input 

A handle  to  the  popup  menu. 
ulPostltlon  (ULONG)  - input 

Position  at  which  to  start  inserting  items, 
hmod  (HMODULE)  - input 

Module  handle  where  ulMenulD  can  be  found. 
ulMenulD  (ULONG)  - input 

Id  of  menu  to  put  Into  popup  menu. 
ulSubMenuld  (ULONG)  - input 

Id  of  submenu  to  put  Into  popup  menu. 

Returns 

Success  Indicator: 

TRUE  Successful  completion 
FALSE  Error  occurred. 

Remarks 

This  instance  method  will  insert  all  menu  items  in  ulMenulD  into  the  pop-up  menu. 
Menu  item  ids  in  open  cascade  must  match  corresponding  openview. 

Class  specific  menu  IDs  should  be  above  WPMENUID_USER. 
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wpInsertPopupMenultems  - 
WPObject  instance  method 


Usage 

This  method  can  be  called  only  during  the  processing  of  wpModifyPopupMenu. 


How  to  Override 

This  method  is  generally  not  overridden. 


Related  Methods 

• wpMenultemSelected 

• wpMenultemHelpSelected 

• wpModifyPopupMenu 

• wpFilterPopupMenu 
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wpInsertSettingsPage  - 
WPObject  instance  method 


#define  INCL_WINWORKPLACE 


ULONG  wpInsertSettingsPage  (WPObject  * self,  HWND  hwndNotebook,  PPAGEINFO  ppagelnfo) 


The  wpInsertSettingsPage  instance  method  is  called  to  insert  a page  into  the  object's  settings 
notebook. 


Parameters 

self  (WPObject  *)  - input 
The  pointer  to  this  object. 
hwndNotebook  (HWND)  - input 

A handle  to  the  setting  notebook, 
ppagelnfo  (PPAGEINFO)  - input 

A pointer  to  the  notebook  page  information. 

Returns 

Page  identifier: 

0 Error  occurred. 

Pageld  Pageld  identifier  for  the  inserted  page. 

Usage 

This  method  can  be  called  only  during  the  processing  of  the  wpAddSettingsPages  method. 

How  to  Override 

This  method  is  generally  not  overridden. 

Related  Methods 

See  Notebook  Control  Window  Messages  for  related  messages. 

• wpAddSettingsPages 
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wpIsCurrentDesktop  - 
WPDesktop  instance  method 


#define  INCL_WINWORKPLACE 


BOOL  wpIsCurrentDesktop  (WPDesktop  * self) 


The  wpIsCurrentDesktop  instance  method  allows  the  desktop  to  specify  whether  it  is  the  active 
desktop  folder  on  the  system. 


Parameters 

self  (WPDesktop  *)  - input 
The  pointer  to  this  object. 


Returns 

Active  desktop  indicator: 

True  This  object  is  the  active  desktop. 

False  This  object  is  not  the  active  desktop  and  should  behave  as  a normal  folder. 

Remarks 

The  active  desktop  is  set  by  the  system  every  time  the  user  profile  is  reset  by  a call  to  the  PrfReset 
function.  Since  there  can  only  be  one  desktop  and  objects  cannot  change  their  class,  desktop  objects 
and  descendents  must  call  wpIsCurrentDesktop  to  determine  if  it  is  the  current  desktop.  Desktop 
folders  which  are  not  active  take  on  the  behavior  of  standard  folder  objects. 

Usage 

This  method  is  called  at  the  beginning  of  every  overridden  method.  If  the  return  is  false,  the  override 
method  should  call  its  parent  without  doing  any  override  processing.  If  the  return  is  true,  override 
processing  can  be  made. 


How  to  Override 

This  method  is  generally  not  overridden. 
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wpMenultemHelpSelected 
WPObject  instance  method 


#define  INCL_WINWORKPLACE 


BOOL  wpMenultemHelpSelected  (WPObject  * self,  ULONG  ulMenuld) 


The  wpMenultemHelpSelected  instance  method  is  called  to  allow  the  object  to  display  the  requested 
help  panel. 

Parameters 

sell  (WPObject  *)  - input 
The  pointer  to  this  object. 
ulMenuld  (ULONG)  - input 

An  unsigned  short  containing  the  object's  menu  id. 


Returns 

Success  indicator: 

TRUE  Successful  completion 
FALSE  Error  occurred. 

Remarks 

The  default  WPObject  class  doesn't  process  this  method  at  all  other  than  to  return  false. 

Usage 

This  method  is  generally  only  called  by  the  system  when  help  on  a popup  menu  item  is  requested. 

How  to  Override 

This  method  should  be  overridden  in  order  to  display  an  appropriate  help  panel  for  the  specified 
menu  item.  This  is  typically  accomplished  by  issuing  a call  to  the  wpDisplayHelp  method. 


Related  Methods 

• wpDisplayHelp 

• wpQueryDefaultHelp 

• wpSetDefaultHelp 

• wpcisQueryDefaultHelp 

• wpMenultemSelected 

• wpModifyPopupMenu 

• wpFilterPopupMenu 

• wpInsertPopupMenultems 
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wpMenultemSelected  - 
WPObject  instance  method 


#define  INCL_WINWORKPLACE 


BOOL  wpMenultemSelected  (WPObject  * self,  HWND  hwndFrame,  ULONG  uiMenuld) 


The  wpMenultemSelected  instance  method  is  called  to  allow  an  object  to  process  a pop-up  menu 
selection. 


Parameters 

self  (WPObject  *)  - input 
The  pointer  to  this  object. 
hwndFrame  (HWND)  - input 
Handle  to  the  frame  window. 
uiMenuld  (ULONG)  - input 

ID  of  selected  pop-up  menu  selected. 

Returns 

Success  indicator: 

TRUE  Successful  completion 
FALSE  Error  occurred. 

Remarks 

Class  specific  Menu  Ids  should  be  above  WPMENUIDJJSER. 

Usage 

This  method  is  generally  only  called  by  the  system  when  a new  pop-up  menu  on  all  item  is  selected. 

How  to  Override 

This  method  should  be  overridden  to  process  class-specific  menu  item  actions  or  to  modify  the 
behavior  of  a menu  item  action  provided  by  an  ancestor  class. 

Related  Methods 

• wpMenultemHelpSelected 

• wpModifyPopupMenu 

• wpFilterPopupMenu 

• wpinsertPopupMenultems 


Chapter  9.  Workplace  Classes,  Instance  Methods,  and  Class  Methods  9-139 


wpModifyPopupMenu  - 
WPObject  instance  method 


#define  INCL_WINWORKPLACE 


BOOL  wpModifyPopupMenu  (WPObject  * self,  HWND  hwndMenu,  HWND  hwndCnr, 

ULONG  ulPosItlon) 


The  wpModifyPopupMenu  instance  method  is  called  to  allow  an  object  to  add  additional  items  to  its 
pop-up  menu. 

Parameters 

self  (WPObject  *)  - input 
The  pointer  to  this  object. 
hwndMenu  (HWND)  - input 
The  menu  handle. 
hwndCnr  (HWND)  - input 

The  handle  to  container  control  window. 
ulPosItlon  (ULONG)  - input 

The  position  to  insert  menu  items. 


Returns 

Success  indicator: 

TRUE  Successful  completion 
FALSE  Error  occurred. 

Remarks 

Class  specific  Menu  Ids  should  be  above  WPMENUIDJJSER.  This  method  will  only  be  called  if  the 
current  pop-up  menu  applies  to  objects  of  the  same  class. 

Usage 

This  method  is  generally  called  by  the  system  when  a request  to  display  the  object's  pop-up  menu  is 
made.  This  method  is  called  following  a call  to  the  wpFilterPopupMenu  method. 


How  to  Override 

This  method  should  be  overridden  in  order  to  add  class-specific  actions  to  the  object's  pop-up  menu. 
Descendent  classes  can  remove  these  actions  by  processing  the  wpFilterPopupMenu  method. 


Related  Methods 

• wpMenultemSelected 

• wpMenultemHelpSelected 

• wpFilterPopupMenu 

• wpinsertPopupMenultems 
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wpMoveObject  - 
WPObject  instance  method 


#define  INCL_WINWORKPLACE 


BOOL  wpMoveObject  (WPObject  * self,  WPFolder  * Folder) 


The  wpMoveObject  instance  method  is  called  to  move  the  object  to  a different  location. 


Parameters 

self  (WPObject  *)  - input 
The  pointer  to  this  object. 

Folder  (WPFolder  *)  - input 

A pointer  to  a folder  object  in  which  to  move  this  object  into.  This  pointer  can  be  determined  by 
issuing  a call  to  wpcisQueryFolder  method. 

Returns 

Success  indicator: 

TRUE  Successful  completion 
FALSE  Error  occurred. 

Usage 

This  method  can  be  called  at  any  time  in  order  to  move  an  object  to  a new  location. 

How  to  Override 

This  method  is  generally  not  overridden  except  by  storage  classes.  The  parent  should  be  called  last 
unless  special  actions  need  to  take  place  when  an  object  is  moved. 

Related  Methods 

• wpCopy  Object 

• wpCreateShadowObject 
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wpOpen  - 

WPObject  instance  method 


#define  INCL_WINWORKPLACE 


HWND  wpOpen  (WPObject  * self,  HWND  hwndCnr,  ULONG  ulVIew,  ULONG  ulparam) 


The  wpOpen  instance  method  is  called  to  open  a view  to  the  object. 


Parameters 

self  (WPObject  *)  - input 
The  pointer  to  this  object. 
hwndCnr  (HWND)  - input 

Handle  of  the  container  window  which  the  object  is  opened  from.  This  value  may  be  set  to 
NULLHANDLE. 


ulVIew  (ULONG)  - input 


Specifies  which  view  to  open. 

OPENCONTENTS  Open  content  view. 

OPENDEFAULT  Open  default  view  (same  as  double-click). 

OPEN_DETAILS  Open  details  view. 

OPEN_HELP  Display  HelpPanel. 

OPEN  RUNNING  Execute  object. 

OPEN  SETTINGS  Open  settings  notebook. 

OPEN_TREE  Open  tree  view. 

OPEN_USER  Class  specific  views  have  a greater  value  than  this. 

ulparam  (ULONG)  - input 
Open  view  parameter. 

This  value  is  (reserved  = NULL)  for  views  supported  by  the  WPObject  class. 


Returns 

Success  indicator: 

NULLHANDLE  Error  occurred. 

Other  Handle  to  either  window  created  or  program  executed. 

Usage 

This  method  can  be  called  at  any  time  in  order  to  open  a view  of  an  object. 


How  to  Override 

This  method  should  be  overridden  in  order  to  process  class-specific  open  views.  This  method  can 
also  be  overridden  in  order  to  modify  the  behavior  defined  an  ancestor  class. 

Related  Methods 

• wpCIose 
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wpPaintCell  - 
WPPalette  instance  method 


#define  INCL_WINWORKPLACE 


BOOL  wpPaintCell  (WPPalette  * self,  PCELL  pCell,  HPS  tips,  PRECTL  pprcl,  BOOL  fHllite) 


The  wpPaintCell  instance  method  is  called  to  paint  a cell. 

Parameters 

self  (WPPalette  *)  - input 
The  pointer  to  the  object. 
pCell  (PCELL)  - input 

A pointer  to  the  CELL  structure  to  be  painted. 
hps(HPS)  - input 

A presentation  space  handle  for  the  cell, 
pprcl  (PRECTL)  - input 

A pointer  to  the  RECTL  structure  for  the  area  to  be  painted. 
fHllite  (BOOL)  - input 

A flag  to  indicate  selected  state. 

TRUE  Cell  is  currently  selected. 

FALSE  Cell  is  not  currently  selected. 

Returns 

Success  indicator. 

TRUE  Successful  completion. 

FALSE  Error  occurred. 

Remarks 

The  default  processing  for  this  method  by  the  WPPalette  class  is  to  paint  a SYSCLR_WINDOW 
background.  If  the  cell  is  highlighted,  a SYSCLRJHIGHLITEBACKGROUND  background  is  painted. 

Usage 

This  method  is  can  be  called  at  any  time  in  order  to  paint  a cell. 

How  to  Override 

This  method  should  be  overriden  by  all  subclasses  that  want  to  display  visual  information  in  the  cell 
window.  It  is  recommended  that  the  parent  method  be  called  first. 
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wpPopulate  - 
WPFolder  instance  method 


#define  INCL_WINWORKPLACE 


BOOL  wpPopulate  (WPFolder  * self,  ULONG  ulReserved,  WPFolder  * Folder, 
BOOL  fFoldersOnly) 


The  wpPopulate  instance  method  is  called  to  allow  the  folder  to  populate  itself. 

Parameters 

self  (WPFolder  *)  - input 
The  pointer  to  this  object. 
ulReserved  (ULONG)  - input 
Reserved  value  must  be  0. 

Folder  (WPFolder  *)  - input 

The  real  name  of  the  folder  to  populate. 
fFoldersOnly  (BOOL)  - input 

The  o red  flag  indicating  type  of  contents  with  which  to  populate  folder: 

TRUE  Populate  with  folder  objects  only. 

FALSE  Populate  with  entire  contents  of  folder. 

Returns 

Success  indicator: 

TRUE  Successful  completion 
FALSE  Error  occurred. 

Remarks 

The  wpPopulate  method  sets  the  folder  flags  depending  upon  the  value  of  fFoldersOnly. 

The  folder  flags  indicate  what  the  current  population  state  of  the  folder  is: 

FOI_POPULATEDWITHALL  folder  is  completely  populated. 

FOI_POPULATEDWITHFOLDERS  folder  is  populated  only  with  subfolders. 

If  the  folder  is  re-populated  when  it  has  already  been  populated  (as  determined  by  inspecting  the 
folder  flags),  no  action  is  taken  on  this  message  apart  from  sending  the  notification  message  back. 

Usage 

This  method  is  generally  called  only  by  the  system  when  the  folder  is  opened. 

How  to  Override 

This  method  can  be  overridden  to  alter  the  contents  of  a folder.  To  filter  contents  added  by  ancestor 
classes,  it  is  important  to  call  the  parent  method  first. 
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wpPrintJobNext  - 
WPJob  instance  method 


#define  INCLJ/VINWORKPLACE 
BOOL  wpPrintJobNext  (WPJob  * self) 

The  wpPrintJobNext  instance  method  is  called  to  print  a job  next. 

Parameters 

self  (WPJob  *)  - input 

The  pointer  to  the  object  to  be  printed  next. 

Returns 

Success  indicator: 

TRUE  Successful  completion 
FALSE  Error  occurred. 

How  to  Override 

This  method  is  generally  not  overridden. 


Chapter  9.  Workplace  Classes,  Instance  Methods,  and  Class  Methods  9-145 


wpPrintMetaFile  - 
WPDataFile  instance  method 


#define  INCL_WINWORKPLACE 


BOOL  wpPrintMetaFile  (WPDataFile  * self,  PPRINTDEST  pPrlntDest) 


The  wpPrintMetaFile  instance  method  is  called  to  print  an  object  of  type  “MetaFile.” 

Parameters 

self  (WPDataFile  *)  - input 

The  pointer  to  this  object. 

pPrlntDest  (PPRINTDEST)  - input 
The  pointer  to  the  print  data. 

It  contains  all  the  parameters  required  to  issue  a DevPostDeviceModes  and  DevOpenDC  function 
calls. 

Returns 

Success  indicator: 

TRUE  Successful  completion 
FALSE  Error  occurred. 

How  to  Override 

This  method  can  be  overridden  by  any  object  class  that  wants  to  replace  the  system  supplied 
MetaFile  print  method. 

Related  Methods 

• wpPrintObject 
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wpPrintObject  - 
WPObject  instance  method 


#define  INCL_WINWORKPLACE 


BOOL  wpPrintObject  (WPObject  * self,  PPRINTDEST  pPrlntDest,  ULONG  ulReserved) 


The  wpPrintObject  instance  method  is  called  to  print  a view  of  the  object. 

Parameters 

self  (WPObject  *)  - input 

The  pointer  to  this  object. 

pPrlntDest  (PPRINTDEST)  - input 
The  pointer  to  print  data. 

It  contains  all  the  parameters  required  to  issue  a DevPostDeviceModes  and  DevOpenDC  function 
calls. 

ulReserved  (ULONG)  - input 
Reserved  value  must  be  0. 


Returns 

Success  indicator: 

TRUE  Successful  completion 
FALSE  Error  occurred. 

Usage 

This  method  can  be  called  at  any  time  in  order  to  print  a view  of  an  object. 


How  to  Override 

This  method  should  be  overridden  in  order  to  modify  the  print  behavior  supported  by  an  ancestor 
class. 

Related  Methods 

• wpPrintMetaFile 

• wpPrintPifFile 

• wpPrintPlainTextFile 

• wpPrintPrinterSpecificFile 

• wpPrintUnknownFile 
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wpPrintPifFile  - 
WPDataFile  instance  method 


#define  INCL_WINWORKPLACE 


BOOL  wpPrintPifFile  (WPDataFile  * self,  PPRINTDEST  pPrlntDest) 


The  wpPrintPifFile  instance  method  is  called  to  print  an  object  of  type  “Pif.” 

Parameters 

self  (WPDataFile  *)  - input 

The  pointer  to  this  object. 

pPrlntDest  (PPRINTDEST)  - input 
The  pointer  to  the  print  data. 

It  contains  all  the  parameters  required  to  issue  a DevPostDeviceModes  and  DevOpenDC  function 
calls. 

Returns 

Success  indicator: 

TRUE  Successful  completion 
FALSE  Error  occurred. 

How  to  Override 

This  method  can  be  overridden  by  any  object  class  that  wants  to  replace  the  system  supplied  Pif  file 
print  method. 

Related  Methods 

• wpPrintObject 
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wpPrintPlainTextFile  - 
WPFileSystem  instance  method 


#define  INCL_WINWORKPLACE 


BOOL  wpPrlnlPialnT extFile  (WPFileSystem  * self,  PPRINTOEST  pPrlntDest) 


The  wpPrintPlainTextFile  instance  method  is  called  to  print  an  object  of  type  “Plain  Text.” 

Parameters 

self  (WPFileSystem  *)  - input 

The  pointer  to  this  object. 

pPrlntDest  (PPRINTDEST)  - input 
The  pointer  to  the  print  data. 

It  contains  all  the  parameters  required  to  issue  a DevPostDeviceModes  and  DevOpenDC  function 
calls. 

Returns 

Success  indicator: 

TRUE  Successful  completion 
FALSE  Error  occurred. 

How  to  Override 

This  method  can  be  overridden  by  any  object  class  that  wants  to  replace  the  system  supplied  Plain 
Text  File  print  method. 

Related  Methods 

• wpPrintObject 


Chapter  9.  Workplace  Classes,  Instance  Methods,  and  Class  Methods  9-149 


wpPrintPrinterSpecificFile  - 
WPDataFile  instance  method 


#define  INCL_WINWORKPLACE 


BOOL  wpPrintPrinterSpecificFile  (WPDataFile  * self,  PPRINTDEST  pPrintDest) 


The  wpPrintPrinterSpecificFile  instance  method  is  called  to  print  an  object  of  type  “Printer-specific 
Data.” 

Parameters 

self  (WPDataFile  *)  - input 

The  pointer  to  this  object. 

pPrintDest  (PPRINTDEST)  - input 
The  pointer  to  the  print  data. 

It  contains  all  the  parameters  required  to  issue  a DevPostDeviceModes  and  DevOpenDC  function 
calls. 

Returns 

Success  indicator: 

TRUE  Successful  completion 
FALSE  Error  occurred. 

How  to  Override 

This  method  can  be  overridden  by  any  object  class  that  wants  to  replace  the  system  supplied 
Printer-specific  File  print  method. 


Related  Methods 

• wpPrintObject 
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wpPrintUnknownFile  - 
WPDataFile  instance  method 


#define  INCL_WINWORKPLACE 


BOOL  wpPrintUnknownFile  (WPDataFile  * self,  PPRINTDEST  pPrlntDest) 


The  wpPrintUnknownFile  instance  method  is  called  to  print  an  object  of  “unknown”  type. 

Parameters 

self  (WPDataFile  *)  - input 

The  pointer  to  this  object. 

pPrlntDest  (PPRINTDEST)  - input 
The  pointer  to  the  print  data. 

It  contains  all  the  parameters  required  to  issue  a DevPostDeviceModes  and  DevOpenDC  function 
calls. 

Returns 

Success  indicator: 

TRUE  Successful  completion 
FALSE  Error  occurred. 

How  to  Override 

This  method  can  be  overridden  by  any  object  class  that  wants  to  replace  the  system  supplied 
Unknown  File  print  method. 

Related  Methods 

• wpPrintObject 
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wpQueryAssociationFilter  - 
WPProgram  instance  method 


#define  INCL_WINWORKPLACE 


PSZ  wpQueryAssociationFilter  (WPProgram  * self) 


The  wpQueryAssociationFilter  instance  method  is  called  to  determine  which  file  title  filters  are  used 
to  associate  data  file  objects  to  this  program  object. 


Parameters 

self  (WPProgram  *)  - input 
The  pointer  to  the  object. 


Returns 

Success  indicator: 

NULL  Error  occurred. 

Other  A pointer  to  a string  containing  file  title  filter(s).  This  string  can  contain  several  file  title 
filters  separated  by  a comma. 

Example:  “*.TXT,  *.DOC” 

Remarks 

The  association  filter  is  used  to  designate  this  program  as  an  available  open  view  for  data  file 
objects  which  have  a title  that  matches  one  of  the  association  filters  which  are  set.  If  a data  file 
object  matches  a filter  in  a program  object  or  program  file  object,  the  title  of  the  program  object  or 
program  file  object  will  appear  in  the  data  file  object's  Open  cascade  of  its  pop-up  menu.  The 
wpQueryAssociationFilter  method  will  return  the  filter  string  set  by  the  last  call  to  the 
wpSetAssociationFilter  method.  The  wpQueryAssociationType  method  can  be  called  to  determine 
which  file  types  are  used  to  associate  data  file  objects  to  this  program  object. 

Usage 

This  method  can  be  called  at  any  time  in  order  to  determine  which  file  title  filters  are  used  to 
associate  data  file  objects  to  this  program  object. 


How  to  Override 

This  method  is  generally  not  overridden. 


Related  Methods 

• wpQueryAssociationType 

• wpSetAssociationFilter 

• wpSetAssociationType 
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wpQueryAssociationFilter  - 
WPProgramFile  instance  method 


#define  INCL_WINWORKPLACE 


PSZ  wpQueryAssociationFilter  (WPProgramFile  * self) 


The  wpQueryAssociationFilter  instance  method  is  called  to  determine  which  file  title  filters  are  used 
to  associate  data  file  objects  to  this  program  object. 


Parameters 

self  (WPProgramFile  *)  - input 
The  pointer  to  the  object. 


Returns 

Success  indicator: 

NULL  Error  occurred. 

Other  A pointer  to  a string  containing  file  title  filters.  This  string  can  contain  several  file  title 
filters  separated  by  a comma. 

Example:  “*.TXT,  *.DOC” 

Remarks 

The  association  filter  is  used  to  designate  this  program  as  an  available  open  view  for  data  file 
objects  which  have  a title  that  matches  one  of  the  association  filters  which  are  set.  If  a data  file 
object  matches  a filter  in  a program  object  or  program  file  object,  the  title  of  the  program  object  or 
program  file  object  will  appear  in  the  data  file  object's  Open  cascade  of  its  pop-up  menu.  The 
wpQueryAssociationFilter  method  will  return  the  filter  string  set  by  the  last  call  to  the 
wpSetAssociationFilter  method.  The  wpQueryAssociationType  method  can  be  called  to  determine 
which  file  types  are  used  to  associate  data  file  objects  to  this  program  object. 

Usage 

This  method  can  be  called  at  any  time  in  order  to  determine  which  file  title  filters  are  used  to 
associate  data  file  objects  to  this  program  object. 


How  to  Override 

This  method  is  generally  not  overridden. 


Related  Methods 

• wpQueryAssociationType 

• wpSetAssociationFilter 

• wpSetAssociationType 
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wpQueryAssociationType  - 
WPProgram  instance  method 


#define  INCL_WINWORKPLACE 


PSZ  wpQueryAssociationType  (WPProgram  * seif) 


The  wpQueryAssociationType  instance  method  is  called  to  determine  which  file  types  are  used  to 
associate  data  file  objects  to  this  program  object. 


Parameters 

self  (WPProgram  *)  - input 
The  pointer  to  the  object. 


Returns 

Success  indicator: 

NULL  Error  occurred. 

Other  A pointer  to  a string  containing  file  type(s).  This  string  can  contain  several  file  title 
filters  separated  by  a comma. 

Example:  "Plain  Text.C  Code" 

Remarks 

The  association  type  is  used  to  designate  this  program  as  an  available  open  view  for  data  file  objects 
which  have  a type  that  matches  one  of  the  association  types  which  are  set.  If  a data  file  object 
matches  a type  in  a program  object  or  program  file  object,  the  title  of  the  program  object  or  program 
file  object  will  appear  in  the  data  file  object's  Open  cascade  of  its  popup  menu. 

The  wpQueryAssociationType  method  will  return  the  type  string  set  by  the  last  call  to  the 
wpSetAssociationType  method. 

The  wpQueryAssociationFilter  method  can  be  called  to  determine  which  file  title  filters  are  used  to 
associate  data  file  objects  to  this  program  object. 

Usage 

This  method  can  be  called  at  any  time  in  order  to  determine  which  file  types  are  used  to  associate 
data  file  objects  to  this  program  object. 


How  to  Override 

This  method  is  generally  not  overridden. 


Related  Methods 

• wpSetAssociationType 

• wpSetType 

• wpQueryType 


9-154  PM  Programming  Reference 


wpQueryAssociationType  - 
WPProgramFile  instance  method 


#define  INCL_WINWORKPLACE 


PSZ  wpQueryAssociationType  (WPProgramFile  * self) 


The  wpQueryAssociationType  instance  method  is  called  to  determine  which  file  types  are  used  to 
associate  data  file  objects  to  this  program  object. 


Parameters 

self  (WPProgramFile  *)  - input 
The  pointer  to  the  object. 


Returns 

Success  indicator: 

NULL  Error  occurred. 

Other  A pointer  to  a string  containing  file  types.  This  string  can  contain  several  file  title  filters 
separated  by  a comma. 

Example:  “Plain  Text, C Code” 

Remarks 

The  association  type  is  used  to  designate  this  program  as  an  available  open  view  for  data  file  objects 
which  have  a type  that  matches  one  of  the  association  types  which  are  set.  If  a data  file  object 
matches  a type  in  a program  object  or  program  file  object,  the  title  of  the  program  object  or  program 
file  object  will  appear  in  the  data  file  object's  Open  cascade  of  its  pop-up  menu.  The 
wpQueryAssociationType  method  will  return  the  type  string  set  by  the  last  call  to  the 
wpSetAssociationType  method.  The  wpQueryAssociationFilter  method  can  be  called  to  determine 
which  file  title  filters  are  used  to  associate  data  file  objects  to  this  program  object. 

Usage 

This  method  can  be  called  at  any  time  in  order  to  determine  which  file  types  are  used  to  associate 
data  file  objects  to  this  program  object. 


How  to  Override 

This  method  is  generally  not  overridden. 


Related  Methods 

• wpSetAssociationType 

• wpSetType 

• wpQueryType 
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wpQueryComputerName  - 
WPPrinter  instance  method 


#define  INCL_WINWORKPLACE 


ULONG  wpQueryComputerName  (WPPrinter  * self,  PSZ  pszComputerName) 


The  wpQueryComputerName  instance  method  is  called  to  query  the  name  of  the  computer  that  the 
print  object  exists  on. 

Parameters 

self  (WPPrinter  *)  - input 

The  pointer  to  the  object  to  be  queried. 
pszComputerName  (PSZ)  - output 

The  returned  computer  name  of  the  object  queried. 

Returns 

0 An  error  occurred. 

1 Successful  - ComputerName  is  local  (NULL). 

2 Successful  - ComputerName  is  on  network.  See  pszComputerName  for  value. 

How  to  Override 

This  method  is  generally  not  overridden. 

Related  Methods 

• wpQueryPrinterName 

• wpSetComputerName 
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wpQueryConfirmations  - 
WPObject  instance  method 


#define  INCLJVINWORKPLACE 


ULONG  wpQueryConfirmations  (WPObject  * self) 


The  wpQueryConfirmations  instance  method  is  called  to  determine  which  confirmations  are  set  on 
this  object. 

Parameters 

self  (WPObject  *)  - input 
The  pointer  to  the  object. 

Returns 

Confirmation  flags. 

NULL 

CONFIRM_DELETE 
CONFIRMDELETEFOLDER 

Usage 

This  method  can  be  called  at  any  time  in  order  to  determine  the  confirmations  set  on  an  object. 

How  to  Override 

This  method  is  generally  not  overridden. 

Related  Methods 

• wpDelete 

• wpFree 

• wpConfirmDelete 


No  confirmations  set. 

Prompt  for  confirmation  for  all  objects. 

Prompt  for  confirmation  for  just  folder  objects. 
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wpQueryContent  - 
WPFolder  instance  method 


#define  INCL_WINWORKPLACE 


WPObject  * wpQueryContent  (WPFolder  * self,  WPObject  * object,  ULONG  ulOptlon) 


The  wpQueryContent  instance  method  is  called  to  allow  the  folder  to  specify  its  contents. 


Parameters 

self  (WPFolder  *)  - input 
The  pointer  to  this  object, 
object  (WPObject  *)  - input 

A pointer  to  a workplace  object.  This  field  is  ignored  unless  QC_NEXT  is  specified  in  ulOption. 
ulOptlon  (ULONG)  - input 

A flag  indicating  the  object  to  query  (QC_FIRST,  QC_NEXT,QC_LAST). 


Returns 

A pointer  to  the  correct  item  in  the  folder's  content  list. 


Remarks 

This  method  allows  the  user  to  query  the  folder's  content  in  various  ways  using  the  ulOption  flag. 
QC_FIRST  returns  the  first  item  in  the  content  list,  QC_LAST  returns  the  last  and  QC_NEXT  will  return 
the  next  item  after  “Object"  in  the  list. 

Usage 

This  method  is  generally  called  to  look  for  a specific  object  or  to  query  the  contents  in  a specific 
folder. 

How  to  Override 

This  method  is  generally  not  overridden. 
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wpQueryDefaultHelp  - 
WPObject  instance  method 


#define  INCL_WINWORKPLACE 


BOOL  wpQueryDefaultHelp  (WPObject  * self,  PULONG  pHelpPanelld,  PSZ  pszHelpLIbrary) 


The  wpQueryDefaultHelp  Instance  method  is  called  to  allow  the  object  to  specify  Its  default  help 
panel. 

Parameters 

self  (WPObject  *)  - input 
The  pointer  to  the  object. 
pHelpPanelld  (PULONG)  - output 
The  pointer  to  the  help  panel  id. 
pszHelpLIbrary  (PSZ)  - output 

The  pointer  to  a buffer  in  which  to  place  the  name  of  help  library.  This  buffer  should  be  the 
length  of  CCHMAXPATH  bytes. 


Returns 

Success  indicator: 

TRUE  Successful  completion 
FALSE  Error  occurred. 

Remarks 

The  default  help  panel  for  this  class  can  be  determined  by  calling  the  wpcIsQueryDefaultHelp 
method. 

Usage 

This  method  can  be  called  at  any  time  in  order  to  determine  the  default  panel  for  this  object. 


How  to  Override 

This  method  is  generally  not  overridden. 

Related  Methods 

• wpDisplayHelp 

• wpMenultemHelpSelected 

• wpSetDefaultHelp 

• wpcIsQueryDefaultHelp 
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wpQueryDefauItView  - 
WPObject  instance  method 


#define  INCL_WINWORKPLACE 


ULONG  wpQueryDefauItView  (WPObject  * self) 


The  wpQueryDefauItView  instance  method  is  called  to  allow  the  object  to  query  its  current  default 
open  view. 


Parameters 

self  (WPObject  *)  - input 
The  pointer  to  this  object. 


Returns 

A flag  indicating  the  default  open  view. 


OPEN_CONTENTS 

OPENDEFAULT 

OPENDETAILS 

OPENHELP 

OPENRUNNING 

OPEN_SETTINGS 

OPENTREE 

OPENUNKNOWN 

OPENUSER 


Open  content  view. 

Open  default  view  (same  as  double-click). 

Open  details  view. 

Display  HelpPanel. 

Execute  object. 

Open  settings  notebook. 

Open  tree  view. 

Unknown  view. 

Class  specific  views  have  a greater  value  than  this. 


Remarks 

This  method  returns  the  default  open  view  for  this  instance.  The  default  open  view  is  displayed  when 
a user  double-clicks  on  the  object  or  when  the  user  selects  Open  without  selecting  an  item  in  the 
open  cascade. 


Usage 

This  method  can  be  called  at  any  time  in  order  to  determine  its  default  open  view. 


How  to  Override 

This  method  is  generally  not  overridden. 


Related  Methods 

• wpcisQueryDefauItView 

• wpSetDefauItView 


9-160  PM  Programming  Reference 


wpQueryDetailsData  - 
WPObject  instance  method 


#define  INCL_WINWORKPLACE 


BOOL  wpQueryDetailsData  (WPObject  * self,  PVOID  *ppDetallsData,  PULONG  pep) 


The  wpQueryDetailsData  instance  method  is  called  to  allow  the  object  to  query  its  current  details 
data. 


Parameters 

self  (WPObject  *)  - input 
The  pointer  to  this  object. 

*ppDetallsData  (PVOID)  - output 

A pointer  to  detail  data  information, 
pep  (PULONG)  - input/output 

The  length  of  *ppDetailsData  buffer.  If  ppDetailsData  is  set  to  NULL,  the  actual  size  of 
ppDetailsData  is  returned  in  pcb. 

Returns 

Success  indicator: 

True  Successful  completion 
False  Error  occurred. 

Remarks 

All  objects  which  have  information  to  display  in  details  view  must  override  this  method. 
'ppDetailsData  is  a pointer  to  the  beginning  of  the  buffer  into  which  details  data  should  be  written. 
The  override  should  write  whatever  data  it  is  responsible  for  and  then  increment  the  pointer  to  the 
beginning  of  the  area  of  the  next  class  in  the  hierarchy  (1  byte  past  the  last  field  for  which  it  is 
responsible).  Note  that  'ppDetailsData  must  be  modified  so  that  the  subclasses  write  in  the 
appropriate  place. 

The  details  data  returned  by  a class  must  match  the  information  returned  in  wpdsQueryDetailsInfo. 

Usage 

This  method  can  be  called  at  any  time  in  order  to  determine  the  current  object  details. 

How  to  Override 

All  objects  which  have  information  to  display  in  details  view  must  override  this  method. 

Note  that  the  parent  method  must  always  be  called  before  writing  the  data  and  adjusting  the  pointer. 


Related  Methods 

• wpcisQueryDetails 

• wpdsQueryDetailsInfo 
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wpQueryDetailsData  - 
WPObject  instance  method 


Example  Code 

For  example,  if  writing  the  following  structure: 

typedef  struct  _SAMPLE_DETAIL_DATA  { 

CDATE  cdate; 

CTIME  ctime; 

PSZ  psz; 

} SAMPLE_DETAIL_DATA; 

the  pointer  would  be  modified  as  follows. 

((PBYTE)  (*ppDetailsData))  +=  sizeof(SAMPLE_DETAIL_DATA) ; 
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wpQueryError  - 
WPObject  instance  method 


#define  INCL_WINWORKPLACE 


ULONG  wpQueryError  (WPObject  * self) 


The  wpQueryError  instance  method  is  called  to  retrieve  the  error  identity  of  the  last  error  condition. 

Parameters 

self  (WPObject  *)  - input 
The  pointer  to  the  object. 


Returns 

Error  identities: 

WPERR_PROTECTED_CLASS 

WPERRINVALIDCLASS 

WPERRJNVALIDSUPERCLASS 

WPERRNOM  EMORY 

WPERRSEMAPHOREERROR 

WPERR_BUFFER_TOO_SMALL 

WPERRCLSLOADMODFAILED 

WPERRCLSPROCADDRFAILED 

WPERROBJWORDLOCATION 

W P ERR_  IN  V ALIDOB  JECT 

WPERR  MEMORY  CLEANUP 

WPERRINVALIDMODULE 

WPERRNOERROR 

WPERRUSER 


Class  is  protected. 

Class  is  invalid. 

Superclass  is  invalid. 

Out  of  memory. 

Semaphore  error. 

Buffer  too  small. 

Unable  to  load  class  library  module. 

Unable  to  find  class  entry  point. 

Bad  object  word  location. 

Object  pointer  is  invalid. 

Cannot  free  memory. 

Invalid  class  library  module. 

No  error  conditions  have  been  set. 
Application-defined  errors  are  above  this  value. 


This  value  can  also  include  any  of  the  base  (ERROR_*)  error  codes. 


Remarks 

The  wpQueryError  method  will  retrieve  the  error  identity  that  was  set  on  this  object  by  the  last  call  to 
the  wpSetError  method. 


Usage 

This  method  can  be  called  at  any  time  in  order  to  determine  the  identity  of  the  last  error  that 
occurred.  This  method  is  typically  called  after  calling  a method  that  returned  a failure. 


How  to  Override 

This  method  is  generally  not  overridden. 


Related  Methods 

• wpSetError 
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wpQueryFIdrAttr  - 
WPFolder  instance  method 


#define  INCL_WINWORKPLACE 


ULONG  wpQueryFIdrAttr  (WPFolder  * self,  ULONG  ulVIew) 


The  wpQueryFIdrAttr  instance  method  is  called  to  allow  the  folder  to  query  its  current  view  attributes 
for  the  WC_CONTAINER  window  used  in  each  view  window. 


Parameters 

self  (WPFolder  *)  - input 
The  pointer  to  this  object. 
ulVIew  (ULONG)  - input 


A flag  indicating  the  view  to  query. 


OPEN_CONTENTS 
OPENDET  AILS 
OPENHELP 
OPENTREE 


Open  content  view. 
Open  details  view. 
Display  HelpPanel. 
Open  tree  view. 


Returns 

Flag  containing  current  folder  view  attribute. 

These  are  the  CV_*  attributes  defined  by  the  Container  Control  Window.  See  CNRINFO  on 
page  A-15  for  a detailed  description. 


Usage 

This  method  can  be  called  at  any  time  in  order  to  determine  the  view  attributes  currently  set. 


How  to  Override 

This  method  is  generally  not  overridden. 


Related  Methods 

• wpQueryFIdrFlags 

• wpQueryFIdrFont 

• wpSetFIdrAttr 

• wpSetFIdrFlags 

• wpSetFIdrFont 
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wpQueryFIdrDetailsClass  - 
WPFolder  instance  method 


#define  INCL.WINWORKPLACE 


MWPObject  * wpQueryFIdrDetailsClass  (WPFolder  * self) 


The  wpQueryFIdrDetailsClass  instance  method  is  called  to  determine  which  class  of  details  are  set 
for  a folder. 

Parameters 

self  (WPFolder  *)  - input 
The  pointer  to  the  object. 


Returns 

Success  indicator: 

NULL  Error  occurred. 

Other  Pointer  to  the  class  object  for  which  details  are  to  be  displayed. 

Remarks 

Since  folders  can  contain  objects  of  different  classes  which  can  have  different  details,  it  is  often 
necessary  for  the  user  to  specify  which  class  of  details  to  be  displayed.  The  value  set  by  this  method 
is  not  used  until  a details  view  of  the  folder  is  opened.  The  wpSetFIdrDetailsClass  method  can  be 
called  to  set  the  current  class  of  details  to  be  displayed. 

Usage 

This  method  can  be  called  at  any  time  in  order  to  determine  the  current  class  of  details  to  be 
displayed. 


How  to  Override 

This  method  is  generally  not  overridden. 


Related  Methods 

• wpSetFIdrDetailsClass 
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wpQueryFIdrFlags  - 
WPFolder  instance  method 


#define  INCL_WINWORKPLACE 


ULONG  wpQueryFIdrFlags  (WPFolder  * self) 


The  wpQueryFIdrFlags  instance  method  is  called  to  allow  the  folder  to  query  its  current  flags. 

Parameters 

self  (WPFolder  *)  - input 
The  pointer  to  this  object. 


Returns 

Flag  indicating  the  current  folder  state. 

FOI_POPULATEDWITHALL  This  flag  is  set  if  the  folder  was  populated  with  all  its 

contents. 

FOI_POPULATEDWITHFOLDERS  This  flag  is  set  if  the  folder  was  populated  only  with  folders 

that  it  contains. 

FOI_WORKAREA  This  flag  is  set  if  the  user  sets  the  workarea  property. 

Usage 

This  method  is  called  at  any  time  in  order  to  determine  a folder's  flag  state. 

How  to  Override 

This  method  is  generally  not  overridden. 

Related  Methods 

• wpQueryFIdrAttr 

• wpQueryFIdrFont 

• wpSetFIdrAttr 

• wpSetFIdrFlags 

• wpSetFIdrFont 
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wpQueryFIdrFont  - 
WPFolder  instance  method 


#define  INCL_WINWORKPLACE 


PSZ  wpQueryFIdrFont  (WPFolder  * self,  ULONG  ulVIew) 


The  wpQueryFIdrFont  instance  method  is  called  to  allow  the  folder  to  query  its  current  font. 


Parameters 

self  (WPFolder  *)  - input 

The  pointer  to  this  object. 

ulVIew  (ULONG)  - input 

A flag  indicating  the  view  to  query. 

OPEN_CONTENTS  Open  content  view. 

OPEN_DETAILS  Open  details  view. 

OPEN_TREE  Open  tree  view. 

Returns 

A pointer  to  the  font  string  for  the  specified  open  view.  The  font  string  is  in  the  format  of  point 
size  followed  by  a period  which  is  followed  by  the  face  name. 

For  example,  “lO.Helvetica.”  (a  presentation  parameter  string). 


Remarks 

There  is  only  one  font  for  each  view.  Concurrent  views  will  all  have  the  same  font. 

Usage 

This  method  can  be  called  at  any  time  in  order  to  determine  the  current  font  for  a view. 

How  to  Override 

This  method  is  generally  not  overridden. 


Related  Methods 

• wpQueryFIdrAttr 

• wpQueryFIdrFlags 

• wpSetFIdrAttr 

• wpSetFIdrFlags 

• wpSetFIdrFont 
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wpQueryHandle  - 
WPObject  instance  method 


#define  INCL_WINWORKPLACE 


HOBJECT  wpQueryHandle  (WPObject  * somSelf) 


The  wpQueryHandle  instance  method  returns  a persistent  object  handle  for  the  given  object 
instance. 

Parameters 

somSelf  (WPObject  *)  - input 

The  pointer  to  the  instance  object. 


Returns 

The  persistent  handle  for  this  object. 


Remarks 

The  object  handle  returned  from  this  method  is  the  same  handle  that  can  be  used  from  the 
WinCreateObject,  WinSetObjectData,  or  WinDestroyObject  function  calls.  The  handle  is  unique  on  a 
given  machine  so  the  returned  object  handle  can  be  passed  to  other  processes,  or  stored  for  later 
use  (even  across  IPLs  of  the  system).  It  is  recommended  that  the  wpQueryHandle  instance  method 
be  used  sparingly  on  file  based  object  classes,  since  the  operating  system  keeps  track  of  the  current 
location  of  every  single  file  object  that  has  been  allocated  an  object  handle.  Performance  may  be 
adversely  affected  if  object  handles  were  obtained  to  every  single  file  system  object  that  was  ever 
awakened. 

Usage 

This  method  can  be  called  at  any  time  to  get  a handle  that  is  both  persistent  across  IPLs  and 
completely  unique  on  the  given  machine. 


How  to  Override 

This  method  should  not  be  overridden 

Related  Methods 

• wpcIsQueryObject 
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wpQuerylcon  - 
WPObject  instance  method 


#define  INCL_WINWORKPLACE 


HPOINTER  wpQuerylcon  (WPObject  * self) 


The  wpQuerylcon  instance  method  is  called  to  allow  the  object  to  query  its  current  icon. 

Parameters 

self  (WPObject  *)  - input 
The  pointer  to  this  object. 


Returns 

Success  indicator: 

NULLHANDLE  Error  occurred. 

Other  Handle  to  an  icon. 

Usage 

This  method  can  be  called  at  any  time  in  order  to  get  the  handle  to  the  current  icon  for  this  object. 

How  to  Override 

This  method  is  generally  not  overridden.  The  default  icon  for  a class  is  typically  set  from  an  override 
of  wpcIsQuerylcon  and  the  instance's  icon  may  be  altered  with  wpSetlcon. 


Related  Methods 

• wpcIsQuerylcon 

• wpQuerylconData 

• wpSetlcon 

• wpSetlconData 
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wpQuery  Icon  Data  - 
WPObject  instance  method 


#define  INCL_WINWORKPLACE 


BOOL  wpQuerylconData  (WPObject  * self,  PICONINFO  pplconlnfo) 


The  wpQuerylconData  instance  method  is  called  to  allow  the  object  to  query  the  data  to  be  used  for 
its  current  icon. 

Parameters 

self  (WPObject  *)  - input 
The  pointer  to  this  object, 
pplconlnfo  (PICONINFO)  - output 

A pointer  to  an  ICONINFO  structure  containing  an  icon  specification. 


Returns 

Success  indicator: 

True  Successful  completion 
False  Error  occurred. 

Remarks 

If  pbBuffer  is  NULL,  the  size  of  the  icon  data  is  returned  in  cbBufferSize. 

Usage 

This  method  is  called  at  any  time  in  order  to  query  the  data  for  the  current  icon  for  this  object. 


How  to  Override 

This  method  is  generally  not  overridden. 


Related  Methods 

• wpAddObjectGeneralPage 

• wpcisQuerylcon 

• wpQuerylcon 

• wpSetlcon 

• wpSetlconData 
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wpQueryLogicalDrive  - 
WPDisk  instance  method 


#define  INCL_WINWORKPLACE 


ULONG  wpQueryLogicalDrive  (WPDisk  * somSelf) 


The  wpQueryLogicalDrive  instance  method  returns  the  logical  drive  number  that  is  represented  by 
this  disk  object. 


Parameters 

somSelf  (WPDisk  *)  - input 

The  pointer  to  the  instance  object. 


Returns 

The  logical  drive  identifier. 

Remarks 

Every  instance  of  the  WPDisk  class  that  is  created  in  the  system  must  represent  a logical  drive 
partition.  There  should  never  be  more  than  one  disk  object  per  logical  drive. 

Usage 

This  method  can  be  called  at  any  time. 

How  to  Override 

This  method  should  not  be  overridden. 
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wpQueryNextlconPos  - 
WPFolder  instance  method 


#define  INCL_WINWORKPLACE 


PPOINTL  wpQueryNextlconPos  (WPFolder  * self) 


The  wpQueryNextlconPos  instance  method  is  called  to  allow  the  folder  to  query  the  next  icon 
position. 


Parameters 

self  (WPFolder  *)  - input 
The  pointer  to  this  object. 


Returns 

A pointer  to  the  next  position  at  which  icons  will  be  inserted. 

Remarks 

The  next  icon  is  the  next  available  parking  space  within  the  folder's  client  area. 

Usage 

This  method  can  be  called  at  any  time  in  order  to  determine  the  next  position  which  objects  will  be 
inserted  in  the  file. 

How  to  Override 

This  method  is  generally  not  overridden. 

Related  Methods 

• wpSetNextlconPos 
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wpQueryPaletteHelp  - 
WPPalette  instance  method 


#define  INCL_WINWORKPLACE 


ULONG  wpQueryPaletteHelp  (WPPalette  * somSelf) 


The  wpQueryPaletteHelp  Instance  method  returns  the  help  panel  ID  that  Is  displayed  when  the  help 
pushbutton  Is  used  from  an  open  palette  view. 


Parameters 

somSelf  (WPPalette  *)  - input 

The  pointer  to  the  instance  object. 


Returns 

The  help  panel  ID  within  this  class's  help  module  as  specified  by  the  wpQueryDefaultHelp 
method  for  this  object  instance. 


Remarks 

This  method  returns  the  help  panel  ID  that  is  visible  from  the  open  palette  view.  That  panel  should 
describe  what  the  palette  cells  represent,  how  to  edit  them,  and  how  to  apply  the  cell  values  to  other 
windows  or  objects.  The  palette  object  can  specify  class  default  and  instance  specific  helps  for  the 
object  in  addition  to  this  specialized  help  which  only  applies  to  the  palette  view. 

Usage 

This  method  may  be  called  at  any  time. 


How  to  Override 

All  subclasses  of  WPPalette  need  to  override  this  method  to  provide  help  about  their  open  palette 
view  window. 

Related  Methods 

• wpQueryDefaultHelp 

• wpcIsQueryDefaultHelp 

• wpSetDefaultHelp 
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wpQueryPalettelnfo  - 
WPPalette  instance  method 


#define  INCL_WINWORKPLACE 


BOOL  wpQueryPalettelnfo  (WPPalette  * self,  PPALINFO  pPallnfo) 


The  wpQueryPalettelnfo  instance  method  is  called  to  determine  current  information  about  the  palette. 

Parameters 

self  (WPPalette  *)  - input 
The  pointer  to  the  object. 
pPallnfo  (PPALINFO)  - input 

A pointer  to  a PALINFO  structure. 

Returns 

Success  indicator. 

TRUE  Successful  completion. 

FALSE  Error  occurred. 

Remarks 

The  palette  information  can  be  set  by  issuing  a call  to  the  wpSetPalettelnfo  method. 

Usage 

This  method  can  be  called  at  any  time  in  order  to  get  current  information  about  the  palette. 

How  to  Override 

This  method  is  generally  not  overridden. 

Related  Methods 

• wpSetPalettelnfo 
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wpQueryPrinterName  - 
WPPrinter  instance  method 


#define  INCL_WINWORKPLACE 


BOOL  wpQueryPrinterName  (WPPrinter  * self,  PSZ  pszPrlnterName) 


The  wpQueryPrinterName  instance  method  is  called  to  query  the  name  of  the  printer. 

Parameters 

self  (WPPrinter  *)  - input 

The  pointer  to  the  object  to  be  queried. 
pszPrlnterName  (PSZ)  - output 

The  returned  printer  name  of  the  object  queried. 

Returns 

Success  indicator: 

TRUE  Successful  completion 
FALSE  Error  occurred. 

How  to  Override 

This  method  is  generally  not  overridden. 

Related  Methods 

• wpQueryComputerName 

• wpSetPrinterName 
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wpQueryProgDetails  - 
WPProgram  instance  method 


#define  INCL_WINWORKPLACE 


BOOL  wpQueryProgDetails  (WPProgram  * self,  PPROGDETAILS  pProgDetails,  PULONG  pSize) 


The  wpQueryProgDetails  instance  method  is  called  to  allow  the  object  to  query  its  program  details. 

Parameters 

self  (WPProgram  *)  - input 
The  pointer  to  this  object. 
pProgDetails  (PPROGDETAILS)  - input 
A pointer  to  the  program  details. 
pSize  (PULONG)  - input/output 

The  size  of  pProgDetails  buffer.  If  NULL  is  specified  for  pProgDetails  then  the  size  of  the  current 
pProgDetails  will  be  returned  in  Size. 

Returns 

Success  indicator: 

TRUE  Successful  completion 
FALSE  Error  occurred. 

Usage 

This  method  can  be  called  at  any  time  in  order  to  determine  the  details  on  this  object. 

How  to  Override 

This  method  is  generally  not  overridden. 

Related  Methods 

• wpSetProgDetails 
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wpQueryProgDetails  - 
WPProgramFile  instance  method 


#define  INCL_WINWORKPLACE 


BOOL  wpQueryProgDetails  (WPProgramFile  * self,  PPROGDETAILS  pProgDetalls, 

PULONG  pSize) 


The  wpQueryProgDetails  instance  method  is  called  to  allow  the  object  to  query  its  program  details. 

Parameters 

self  (WPProgramFile  *)  - input 
The  pointer  to  this  object. 
pProgDetalls  (PPROGDETAILS)  - input 
A pointer  to  the  program  details. 
pSize  (PULONG)  - input/output 

The  size  of  pProgDetails  buffer.  If  NULL  is  specified  for  pProgDetails  then  the  size  of  the  current 
pProgDetalls  will  be  returned  in  Size. 

Returns 

Success  indicator: 

TRUE  Successful  completion 
FALSE  Error  occurred. 

Usage 

This  method  can  be  called  at  any  time  in  order  to  determine  the  details  on  this  object. 

How  to  Override 

This  method  is  generally  not  overridden. 

Related  Methods 

• wpSetProgDetails 
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wpQueryRealName  - 
WPFileSystem  instance  method 


#define  INCL_WINWORKPLACE 


BOOL  wpQueryRealName  (WPFileSystem  * self,  PSZ  pszFllename,  PULONG  pcb, 

BOOL  fQualified) 


The  wpQueryRealName  instance  method  is  called  to  allow  the  object  to  query  its  physical  file  name. 

Parameters 

self  (WPFileSystem  *)  - input 
The  pointer  to  this  object. 
pszFllename  (PSZ)  - output 

The  pointer  to  the  buffer  in  which  to  place  the  real  file  name  of  the  object, 
pcb  (PULONG)  - input/output 

The  size  of  the  file  name  buffer.  If  pszFileName  is  set  to  NULL,  the  actual  length  of  the  file  is 
returned. 

fQualified  (BOOL)  - input 
Success  indicator: 

TRUE  Return  the  fully  qualified  file  name. 

FALSE  Return  the  unqualified  file  name. 

Returns 

Success  indicator: 

TRUE  Successful  completion. 

FALSE  An  error  occurred. 

Remarks 

This  method  returns  the  fully  qualified  pathname  for  this  object.  Generally,  the  object's  real  name 
and  an  object's  title  are  the  same.  For  file  systems  which  don't  support  the  features  of  a title,  for 
example,  characters,  mixed  case,  and  spaces,  the  title  is  stored  in  the  .LONGNAME  extended 
attribute  and  then  the  title  and  real  name  may  differ.  The  real  name  of  the  file  object  can  be  used 
with  any  of  the  DOSXXX  functions  which  act  on  file  names. 

Usage 

This  method  can  be  called  at  any  time  in  order  to  determine  the  physical  file  name  for  this  object. 


How  to  Override 

This  method  is  generally  not  overridden. 


Related  Methods 

• wpQueryType 

• wpSetRealName 

• wpSetTitle 
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wpQueryRootFolder  - 
WPDisk  instance  method 


#define  INCL_WINWORKPLACE 


WPRootFolder  * wpQueryRootFolder  (WPDisk  * somSelf) 


The  wpQueryRootFolder  instance  method  returns  the  root  folder  object  for  the  logical  drive  that  is 
represented  by  the  WPDisk  object. 


Parameters 

somSelf  (WPDisk  *)  - input 

The  pointer  to  the  instance  object. 


Returns 

The  root  folder  object.  Null  if  an  error  occurred. 

Remarks 

Every  instance  of  the  WPDisk  class  that  is  created  in  the  system  points  to  a root  folder,  the  root 
directory  of  the  logical  device  that  the  disk  object  represents. 

Usage 

This  method  can  be  called  at  any  time. 

How  to  Override 

This  method  should  not  be  overridden. 
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wpQueryShadowedObject  - 
WPShadow  instance  method 


#define  INCL_WINWORKPLACE 


WPObject  * wpQueryShadowedObject  (WPShadow  * self,  BOOL  fLock) 


The  wpQueryShadowedObject  instance  method  is  called  to  allow  the  shadow  object  to  query  the 
object  with  which  it  is  currently  linked. 


Parameters 

self  (WPShadow  *)  - input 

The  pointer  to  this  object. 

fLock  (BOOL)  - input 
The  lock  object  flag. 

If  this  flag  is  false,  the  newly  created  object  will  be  made  dormant  whenever  the  object  and  the 
folder  containing  the  object  are  closed.  If  this  flag  is  true,  the  new  flag  will  remain  awake  until 
the  caller  issues  the  wpUnlockObject  method  on  it. 


Returns 

Success  indicator: 

NULL  Error  occurred. 

Other  A pointer  to  the  object  with  which  this  shadow  is  linked. 

Usage 

This  method  is  called  at  any  time  in  order  to  determine  the  object  with  which  this  shadow  is  currently 
linked. 

How  to  Override 

This  method  is  generally  not  overridden. 

Related  Methods 

• wpCreateShadowObject 


9-180  PM  Programming  Reference 


wpQueryStyle  - 
WPObject  instance  method 


#define  INCL_WINWORKPLACE 


ULONG  wpQueryStyle  (WPObject  * self) 


The  wpQueryStyle  instance  method  allows  the  object  to  query  its  current  class  style. 

Parameters 

self  (WPObject  *)  - input 
The  pointer  to  this  object. 


Returns 

The  flags  which  are  ored  together  to  indicate  the  object's  style. 


OBJSTYLE_NOCOPY 

OBJSTYLENODELETE 

OBJSTYLENODRAG 

OBJSTYLENOSHADOW 

OBJSTYLENOMOVE 

OBJSTYLENOPRINT 

OBJSTYLENOTDEFAULTICON 

OBJST  YLE_TEM  PLATE 

OBJSTYLE  NOTVISIBLE 

OBJSTYLENORENAME 


Cannot  be  copied. 

Cannot  be  deleted. 

Cannot  be  dragged. 

Cannot  have  shadow  created. 

Cannot  move. 

Cannot  be  printed. 

Destroy  icon  when  object  goes  dormant 
This  object  is  a template. 

The  object  is  hidden. 

Cannot  be  renamed. 


Usage 

This  method  can  be  called  at  any  time  in  order  to  determine  the  current  style  for  an  object  class.  To 
determine  the  default  style  for  an  object  class,  the  wpcisQueryStyle  method  should  be  called. 


How  to  Override 

This  method  is  generally  not  overridden. 


Related  Methods 

• wpcisQueryStyle 

• wpSetStyle 
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wpQueryTitle  - 
WPObject  instance  method 


#define  INCL_WINWORKPLACE 


PSZ  wpQueryTitle  (WPObject  * self) 


The  wpQueryTitle  instance  method  is  called  to  allow  the  object  to  query  its  current  title. 

Parameters 

self  (WPObject  *)  - input 
The  pointer  to  this  object. 


Returns 

A pointer  to  the  object's  title. 

Remarks 

The  object's  title  may  get  altered  by  the  user  at  any  time.  Objects  should  always  use  this  method  to 
access  the  current  title  and  never  store  the  string  pointer  that  is  returned. 

Usage 

This  method  can  be  called  at  any  time  in  order  to  determine  the  current  title  of  an  object.  To 
determine  the  default  title  for  an  object's  class,  the  wpcisQuery Title  method  should  be  called. 

How  to  Override 

This  method  is  generally  not  overridden. 


Related  Methods 

• wpcisQuery  Title 

• wpSetTitle 
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wpQueryType  - 
WPFileSystem  instance  method 


#define  INCL_WINWORKPLACE 


PSZ  wpQueryType  (WPFileSystem  * self) 


The  wpQueryType  instance  method  is  called  to  allow  the  object  to  query  the  type  of  its  file. 


Parameters 

self  (WPFileSystem  *)  - input 
The  pointer  to  this  object. 


Returns 

The  pointer  to  a buffer  containing  file  type.  This  string  can  contain  a list  of  types  delineated  by  a 
line  feed  character.  For  example,  “Plain  Text\nC  Code.” 


Remarks 

This  method  returns  the  type  of  a file-system- based  object.  The  type  of  a file  is  designated  by  its 
.TYPE  extended  attribute  value. 

Usage 

This  method  can  be  called  at  any  time  in  order  to  determine  the  type  of  the  file  object. 


How  to  Override 

This  method  is  generally  not  overridden. 


Related  Methods 

• wpAddFileTypePage 

• wpSetTitle 
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wpRedrawCell  - 
WPPalette  instance  method 


#define  INCL_WINWORKPLACE 


BOOL  wpRedrawCell  (WPPalette  * somSelf,  PCELL  pCell) 


The  wpRedrawCell  instance  method  forces  a palette  object  to  repaint  the  specified  cell  area. 

Parameters 

somSelf  (WPPalette  *)  - input 

The  pointer  to  the  instance  object. 
pCell  (PCELL)  - input 

The  pointer  to  the  cell  within  the  palette  that  needs  repainting. 


Returns 

TRUE  The  method  call  was  successful. 

FALSE  The  method  call  was  unsuccessful. 

Remarks 

This  method  is  used  as  cell  values  within  the  palette  are  altered.  For  example,  when  the  color 
selector  dialog  is  changing  the  color  of  a palette  cell  in  the  color  palette  this  method  is  invoked  to 
refresh  the  color  back  in  the  open  views  of  the  color  palette  object. 

Usage 

This  method  may  be  called  at  any  time  to  force  the  palette  object  to  repaint  the  specified  cell  in  all  of 
its  currently  open  views. 


How  to  Override 

Overriding  this  method  is  not  recommended 


Related  Methods 

• wpPaintCell 
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wpRefresh  - 

WPFileSystem  instance  method 


#define  INCL_WINWORKPLACE 


BOOL  wpRefresh  (WPFileSystem  * self,  ULONG  ulVIew,  PVOID  pReserved) 


The  wpRefresh  instance  method  is  called  to  refresh  the  contents  of  a folder. 

Parameters 

self  (WPFileSystem  *)  - input 

The  pointer  to  the  object. 

ulVIew  (ULONG)  - input 

A flag  indicating  which  view  to  refresh. 

OPEN_CONTENT  Refresh  content  (icon)  view. 

OPEN_DETAILS  Refresh  details  view. 

pReserved  (PVOID)  - input 

Reserved  value  must  be  0. 

Returns 

Success  indicator. 

TRUE  Successful  completion. 

FALSE  Error  occurred. 

Usage 

This  method  can  be  called  at  any  time  to  refresh  the  contents  of  a folder. 

How  to  Override 

This  method  is  generally  not  overridden. 

Related  Methods 

• wpPopulate 


Chapter  9.  Workplace  Classes,  Instance  Methods,  and  Class  Methods  9-185 


wpRegisterView  - 
WPObject  instance  method 


#define  INCL_WINWORKPLACE 


BOOL  wpRegisterView  (WPObject  * self,  HWND  hwndFrame,  PSZ  pszVIewTItie) 


The  wpRegisterView  instance  method  is  called  to  allow  the  object  to  register  a new  open  view. 


Parameters 

sell  (WPObject  *)  - input 
The  pointer  to  this  object. 
hwndFrame  (HWND)  - input 

A handle  to  the  frame  window  containing  the  new  view. 
pszVIewTItie  (PSZ)  - input 

The  pointer  to  a string  containing  name  of  view. 

Returns 

Success  indicator: 

True  Successful  completion 
False  Error  occurred. 

Remarks 

Registering  a view  will  set  the  object  title  as  the  title  of  the  frame  window  and  add  a view  title  as  the 
current  view  in  window  list  and  title  bar.  In-use  emphasis  is  managed  by  the  wpAddToObjectUseList 
method. 

Usage 

This  method  is  generally  called  during  the  processing  of  the  wpOpen  method  in  order  to  register  a 
new  view  with  the  object. 

How  to  Override 

This  method  is  generally  not  overridden. 

Related  Methods 

• wpAddToObjUseList 
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wpReleaseJob  - 
WPJob  instance  method 


#define  INCL_WINWORKPLACE 


BOOL  wpReleaseJob  (WPJob  * self) 


The  wpReleaseJob  instance  method  is  called  to  release  a job  object. 

Parameters 

self  (WPJob  *)  - input 

The  pointer  to  the  object  to  be  released. 

Returns 

Success  indicator: 

TRUE  Successful  completion 
FALSE  Error  occurred. 

How  to  Override 

This  method  is  generally  not  overridden. 

Related  Methods 

• wpHoIdJob 
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wpReleasePrinter  - 
WPPrinter  instance  method 


#define  INCL_WINWORKPLACE 


BOOL  wpReleasePrinter  (WPPrinter  * self) 


The  wpReleasePrinter  instance  method  is  called  to  release  a print  object. 

Parameters 

self  (WPPrinter  *)  - input 

The  pointer  to  the  object  to  be  released. 

Returns 

Success  indicator: 

TRUE  Successful  completion 
FALSE  Error  occurred. 

How  to  Override 

This  method  is  generally  not  overridden. 

Related  Methods 

• wpHoldPrinter 
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wpRender  - 

WPObject  instance  method 


#define  INCL_WINWORKPLACE 


M RESULT  wpRender  (WPObject  * self,  PORAGTRANSFER  ppdxfer) 


The  wpRender  instance  method  is  called  to  request  a drag  or  drop  rendering  format  from  the  object. 

Parameters 

self  (WPObject  *)  - input 
The  pointer  to  the  object, 
ppdxfer  (PDRAGTRANSFER)  - input 

A pointer  to  a DRAGTRANSFER  structure. 


Returns 

Refer  to  the  “DM_RENDER”  on  page  29-10  message  for  a description  of  the  return  value. 


Remarks 

The  wpRender  method  is  called  when  the  object  receives  a DM_RENDER  message.  Refer  to  the 
DM_RENDER  message  for  more  information. 

Usage 

This  method  is  generally  called  only  by  the  system  as  the  folder  containing  the  object  processed  by 
the  DM_RENDER  message. 


How  to  Override 

This  method  should  be  overridden  to  return  a class-specific  rendering  mechanism  and  format. 


Related  Methods 

• wpDragOver 

• wpDrop 

• wpFormatDragltem 

• wpRenderComplete 

• wpEndConversation 
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wpRenderComplete  - 
WPObject  instance  method 


#define  INCL_WINWORKPLACE 


M RESULT  wpRenderComplete  (WPObject  * self,  PDRAGTRANSFER  ppdxfer,  ULONG  ulResult) 


The  wpRenderComplete  instance  method  is  called  to  notify  the  object  that  the  drag  or  drop  rendering 
request  is  complete. 


Parameters 

self  (WPObject  *)  - input 
The  pointer  to  the  object, 
ppdxfer  (PDRAGTRANSFER)  - input 

A pointer  to  a DRAGTRANSFER  structure. 
ulResult  (ULONG)  - input 

The  flag  indicating  whether  the  operation  was  performed  successfully.  Refer  to 
“DMRENDERCOMPLETE"  on  page  29-11  for  more  information  about  this  parameter. 

Returns 

Refer  to  the  DM  RENDERCOMPLETE  message  for  a description  of  the  return  value. 

Remarks 

The  wpRenderComplete  method  is  called  when  the  object  receives  a DM_RENDERCOMPLETE 
message.  Refer  to  the  DM  RENDERCOMPLETE  message  for  more  information. 

Usage 

This  method  is  generally  called  only  by  the  system  as  the  folder  containing  the  object  processed  by 
the  DM  RENDERCOMPLETE  message. 

How  to  Override 

This  method  should  be  overridden  if  the  class  has  a special  rendering  mechanism  and  format. 


Related  Methods 

• wpDragOver 

• wpDrop 

• wpFormatDragltem 

• wpRender 

• wpEndConversation 
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wpRestore  - 
WPObject  instance  method 


#define  INCL_WINWORKPLACE 


BOOL  wpRestore  (WPOb|ect  * self) 


The  wpRestore  instance  method  is  called  to  allow  the  object  to  restore  its  views  from  the  hidden  or 
minimized  states. 

Parameters 

self  (WPObject  *)  - input 
The  pointer  to  this  object. 


Returns 

Success  indicator: 

True  Successful  completion 
False  Error  occurred. 

Remarks 

This  method  is  the  inverse  of  the  wpHide  method. 

Usage 

This  method  can  be  called  at  any  time  in  order  to  restore  all  views  of  this  object  from  the  hidden  or 
minimized  state. 

How  to  Override 

This  method  is  generally  not  overridden. 

Related  Methods 

• wpHide 
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wpRestoreData  - 
WPObject  instance  method 


#define  INCL_WINWORKPLACE 


BOOL  wpRestoreData  (WPObject  * self,  PSZ  pszClass,  ULONG  ulKey,  PBYTE  pbValue, 
PULONG  cbValue) 


The  wpRestoreData  instance  method  is  called  to  allow  the  object  to  restore  its  binary  instance  data. 


Parameters 

self  (WPObject  *)  - input 
The  pointer  to  this  object. 
pszClass  (PSZ)  - input 

A pointer  to  a zero  terminated  string  which  contains  any  unique  string.  The  class  name  is 
recommended  but  not  enforced. 

ulKey  (ULONG)  - input 

A class  defined  identifier  that  correlates  to  a particular  instance  data  variable. 
pbValue  (PBYTE)  - input/output 

The  address  of  the  data  to  be  restored. 
cbValue  (PULONG)  - input/output 

The  size  of  the  data  block  to  be  restored.  If  pbValue  is  NULL,  the  actual  size  will  be  returned  in 
cbValue. 

Returns 

Success  indicator: 

TRUE  Successful  completion 
FALSE  Error  occurred. 

Remarks 

This  method  restores  data  that  was  saved  by  a call  to  wpSaveData. 

Usage 

This  method  can  be  called  only  during  the  processing  of  the  wpRestoreState  method. 


How  to  Override 

This  method  is  generally  not  overridden. 


Related  Methods 

• wpRestoreLong 

• wpRestoreState 

• wpRestoreString 

• wpSaveData 

• wpSavelmmediate 

• wpSaveLong 

• wpSaveState 

• wpSaveString 
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wpRestoreLong  - 
WPObject  instance  method 


#define  INCL_WINWORKPLACE 


BOOL  wpRestoreLong  (WPObject  * self,  PSZ  pszClass,  ULONG  ulKey,  PULONG  pValue) 


The  wpRestoreLong  instance  method  is  called  to  allow  the  object  to  restore  a 32-bit  instance  data 
value. 

Parameters 

self  (WPObject  *)  - input 
The  pointer  to  this  object. 
pszClass  (PSZ)  - input 

A pointer  to  a zero  terminated  string  which  contains  any  unique  string.  The  class  name  is 
recommended  but  not  enforced. 

ulKey  (ULONG)  - input 

A class  defined  identifier  that  correlates  to  a particular  instance  data  variable. 
pValue  (PULONG)  - output 

The  address  of  the  long  value. 


Returns 

Success  indicator: 

TRUE  Successful  completion 
FALSE  Error  occurred. 

Remarks 

This  method  restores  a 32-bit  data  value  that  was  saved  by  a call  to  wpSaveLong. 

Usage 

This  method  can  be  called  only  during  the  processing  of  the  wpRestoreState  method. 

How  to  Override 

This  method  is  generally  not  overridden. 


Related  Methods 

• wpRestoreData 

• wpRestoreState 

• wpRestoreString 

• wpSaveData 

• wpSave  Immediate 

• wpSaveLong 

• wpSaveState 

• wpSaveString 
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wpRestoreState  - 
WPObject  instance  method 


#define  INCL_WINWORKPLACE 


BOOL  wpRestoreState  (WPObject  * self,  ULONG  ui  Re  served) 


This  method  restores  the  state  of  the  object  which  was  saved  during  the  processing  of  the 
wpSaveState  method. 

Parameters 

self  (WPObject  *)  - input 
The  pointer  to  this  object. 
ulReserved  (ULONG)  - input 

The  reserved  value  must  be  0. 


Returns 

Success  indicator: 

True  Successful  completion 
False  Error  occurred. 

Remarks 

This  method  restores  the  state  of  the  object  which  was  saved  during  the  processing  of  the 
wpSaveState  method. 

Usage 

This  method  is  generally  called  only  by  the  system  while  it  is  processing  the  wpinitData  method. 


How  to  Override 

This  method  should  be  overridden  by  all  classes  which  provide  settings  that  can  be  saved.  An 
override  of  the  wpSaveState  method  is  a prerequisite  if  persistent  instance  data  is  desired. 

Override  processing  of  this  method  typically  includes  a series  of  calls  to  any  combination  of  the 
restore  state  methods: 

• wpRestoreData 

• wpRestoreLong 

• wpRestoreString 


Related  Methods 

• wpRestoreData 

• wpRestoreLong 

• wpRestoreString 

• wpSaveData 

• wpSavelmmediate 

• wpSaveLong 

• wpSaveState 

• wpSaveString 
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wpRestoreString  - 
WPObject  instance  method 


#define  INCL_WINWORKPLACE 


BOOL  wpRestoreString  (WPObject  * self,  PSZ  pszClass,  ULONG  ulKey,  PSZ  pszValue, 

PULONG  pulValue) 

The  wpRestoreString  instance  method  is  called  to  allow  the  object  to  restore  an  ASCIIZ  instance  data 
string. 

Parameters 

self  (WPObject  *)  - input 
The  pointer  to  this  object. 
pszClass  (PSZ)  - input 

A pointer  to  a zero  terminated  string  which  contains  any  unique  string.  The  class  name  is 
recommended  but  not  enforced. 

ulKey  (ULONG)  - input 

A class  defined  identifier  that  correlates  to  a particular  instance  data  variable. 
pszValue  (PSZ)  - input/output 

The  address  of  the  string  to  be  restored. 
pulValue  (PULONG)  - input/output 

The  size  of  the  string  to  be  restored.  If  pszValue  is  NULL,  the  actual  size  will  be  returned  in 
pulValue. 

Returns 

Success  indicator: 

TRUE  Successful  completion 
FALSE  Error  occurred. 

Remarks 

This  method  restores  an  ASCIIZ  string  that  was  saved  by  a call  to  wpSaveString. 

Usage 

This  method  can  be  called  only  during  the  processing  of  the  wpRestoreState  method. 


How  to  Override 

This  method  is  generally  not  overridden. 


Related  Methods 

• wpRestoreData 

• wpRestoreLong 

• wpRestoreState 

• wpSaveData 

• wpSavelmmediate 

• wpSaveLong 

• wpSaveState 

• wpSaveString 
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wpSaveData  - 
WPObject  instance  method 


#define  INCL_WINWORKPLACE 


BOOL  wpSaveData  (WPObject  * self,  PSZ  pszClass,  ULONG  ulKey,  PBYTE  pbValue, 
ULONG  u IValue) 


The  wpSaveData  instance  method  is  called  to  allow  an  object  to  save  its  binary  instance  data. 


Parameters 

self  (WPObject  *)  - input 
The  pointer  to  this  object. 
pszClass  (PSZ)  - input 

A pointer  to  a zero  terminated  string  which  contains  any  unique  string.  The  class  name  is 
recommended  but  not  enforced. 

ulKey  (ULONG)  - input 

A class  defined  identifier  that  correlates  to  a particular  instance  data  variable. 
pbValue  (PBYTE)  - input 

The  address  of  the  block  of  data  to  be  stored, 
u IValue  (ULONG)  - input 

The  size  of  the  block  of  data  to  be  stored. 


Returns 

Success  indicator: 

TRUE  Successful  completion 
FALSE  Error  occurred. 

Remarks 

The  saved  data  can  be  restored  by  issuing  a call  to  wpRestoreData. 

Usage 

This  method  can  be  called  only  during  the  processing  of  the  wpSaveState  method. 

How  to  Override 

This  method  is  generally  not  overridden. 


Related  Methods 

• wpRestoreData 

• wpRestoreLong 

• wpRestoreState 

• wpRestoreString 

• wpSavelmmediate 

• wpSaveLong 

• wpSaveState 

• wpSaveString 
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wpSaveDeferred  - 
WPObject  instance  method 


#define  INCL_WINWORKPLACE 


BOOL  wpSaveDeferred  (WPPalette  * somSelf) 


The  wpSaveDeferred  instance  method  tells  the  system  to  make  the  object  to  save  itself 
asynchronously. 


Parameters 

somSelf  (WPPalette  *)  - input 

The  pointer  to  the  instance  object. 


Returns 

TRUE  The  save  request  was  accepted. 

FALSE  The  save  request  was  not  accepted. 

Remarks 

The  system  maintains  a list  of  objects  that  currently  need  to  be  saved  and  will  periodically  ask  those 
objects  to  save  their  state  data  to  persistent  storage  using  the  wpSavelmmediate  method.  The 
wpSaveDeferred  method  should  always  be  used  in  preference  to  the  wpSavelmmediate  method 
because  of  performance.  The  only  exception  is  if  the  state  data  was  changed  in  some  critical  way. 
For  example,  if  the  object  wanted  to  save  a new  password,  it  would  use  wpSavelmmediate  instead  of 
wpSaveDeferred  to  guarantee  that  the  password  has  been  saved  before  continuing. 

Usage 

This  method  should  be  called  by  all  object  classes  whenever  state  data  is  altered.  The  workplace 
classes  invoke  this  method  each  time  a wpSetXXX  method  is  used. 


How  to  Override 

This  method  should  not  be  overridden 

Related  Methods 

• wpSavelmmediate 
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wpSavelmmediate  - 
WPObject  instance  method 


#define  INCL_WINWORKPLACE 


BOOL  wpSavelmmediate  (WPObject  * self) 


The  wpSavelmmediate  instance  method  is  called  to  allow  the  object  to  save  its  current  state. 


Parameters 

self  (WPObject  *)  - input 
The  pointer  to  this  object. 


Returns 

Success  indicator: 

True  Successful  completion 
False  Error  occurred. 

Remarks 

This  method  will  cause  the  wpSaveState  method  to  be  called. 

Usage 

This  method  is  called  automatically  for  all  objects  when  they  are  made  dormant  or  when  the  system 
is  shut  down.  However,  an  object  can  call  this  method  on  itself  at  any  time  when  a critical  instance 
variable  is  changed. 


How  to  Override 

This  method  is  generally  not  overridden. 


Related  Methods 

• wpRestoreData 

• wpRestoreLong 

• wpRestoreState 

• wpRestoreString 

• wpSaveData 

• wpSaveLong 

• wpSaveState 

• wpSaveString 
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wpSaveLong  - 
WPObject  instance  method 


#define  INCL_WINWORKPLACE 


BOOL  wpSaveLong  (WPObject  * self,  PSZ  pszClass,  ULONG  ulKeyle,  ULONG  ulValue) 


The  wpSaveLong  instance  method  is  called  to  allow  the  object  to  save  a 32-bit  instance  data  value. 


Parameters 

self  (WPObject  *)  - input 
The  pointer  to  this  object. 
pszClass  (PSZ)  - input 

A pointer  to  a zero  terminated  string  which  contains  any  unique  string.  The  class  name  is 
recommended  but  not  enforced. 

ulKeyle  (ULONG)  - input 

A class  defined  identifier  that  correlates  to  a particular  instance  data  variable. 
ulValue  (ULONG)  - input 

The  value  (ULONG)  to  be  stored. 


Returns 

Success  indicator: 

TRUE  Successful  completion 
FALSE  Error  occurred. 

Remarks 

The  saved  32-bit  data  value  can  be  restored  by  issuing  a call  to  wpRestoreLong. 

Usage 

This  method  can  be  called  only  during  the  processing  of  the  wpSaveState  method. 

How  to  Override 

This  method  is  generally  not  overridden. 


Related  Methods 

• wpRestoreData 

• wpRestoreLong 

• wpRestoreState 

• wpRestoreString 

• wpSaveData 

• wpSavelmmediate 

• wpSaveState 

• wpSaveString 
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wpSaveState  - 
WPObject  instance  method 


#define  INCL_WINWORKPLACE 


BOOL  wpSaveState  (WPObject  * self) 


The  wpSaveState  instance  method  is  called  to  allow  the  object  to  save  its  state. 


Parameters 

self  (WPObject  *)  - input 
The  pointer  to  this  object. 


Returns 

Success  indicator: 

TRUE  Successful  completion 
FALSE  Error  occurred. 

Remarks 

The  saved  state  of  the  object  is  restored  during  the  processing  of  the  wpRestoreState  method. 

Usage 

This  method  is  generally  called  by  the  system  while  it  is  processing  either  the  wpCIose  or 
wpSavelmmediate  methods.  If  an  immediate  save  is  required,  the  wpSavelmmediate  method  can  be 
called. 

How  to  Override 

This  method  should  be  overridden  by  all  classes  which  provide  savable  settings.  An  override  of  the 
wpRestoreState  method  is  a prerequisite. 

Override  processing  of  this  method  typically  includes  a series  of  calls  to  any  combination  of  the  save 
state  methods: 

• wpSaveData 

• wpSaveLong 

• wpSaveString 


Related  Methods 

• wpRestoreData 

• wpRestoreLong 

• wpRestoreState 

• wpRestoreString 

• wpSaveData 

• wpSavelmmediate 

• wpSaveLong 

• wpSaveString 
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wpSaveString  - 
WPObject  instance  method 


#define  INCL_WINWORKPLACE 


BOOL  wpSaveString  (WPObject  * self,  PSZ  pszClass,  ULONG  ulKey,  PSZ  pszValue) 


The  wpSaveString  instance  method  is  called  to  allow  the  object  to  save  an  ASCIIZ  instance  data 
string. 


Parameters 

self  (WPObject  *)  - input 
The  pointer  to  this  object. 
pszClass  (PSZ)  - input 

A pointer  to  a zero  terminated  string  which  contains  any  unique  string.  The  class  name  is 
recommended  but  not  enforced. 

ulKey  (ULONG)  - input 

A class  defined  identifier  that  correlates  to  a particular  instance  data  variable. 
pszValue  (PSZ)  - input 
String  to  be  stored. 


Returns 

Success  indicator: 

TRUE  Successful  completion 
FALSE  Error  occurred. 

Remarks 

The  saved  ASCIIZ  string  can  be  restored  by  issuing  a call  to  wpRestoreString. 

Usage 

This  method  can  be  called  only  during  the  processing  of  the  wpSaveState  method. 


How  to  Override 

This  method  is  generally  not  overridden. 


Related  Methods 

• wpRestoreData 

• wpRestoreLong 

• wpRestoreState 

• wpRestoreString 

• wpSaveData 

• wpSavelmmediate 

• wpSaveLong 

• wpSaveState 
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wpScanSetupString  - 
WPObject  instance  method 


#define  INCL_WINWORKPLACE 


BOOL  wpScanSetupString  (WPObject  * self,  PSZ  pszSetupStrlng,  PSZ  pszKey,  PSZ  pszValue, 

PULONG  pcb Value) 


The  wpScanSetupString  instance  method  is  called  to  allow  an  object  to  parse  the  setup  string  that  is 
passed  when  the  object  is  created. 

Parameters 

self  (WPObject  *)  - input 
The  pointer  to  this  object. 
pszSetupStrlng  (PSZ)  - input 

The  class  specific  setup  parameters  for  an  object. 
pszKey  (PSZ)  - input 
The  key  to  scan  for. 
pszValue  (PSZ)  - input 
The  buffer  for  the  value. 
pcbValue  (PULONG)  - input/output 

If  pszValue  is  null,  the  length  of  the  string  plus  one  is  returned  in  pcbValue. 

Returns 

Success  indicator: 

True  Successful  completion 
False  Error  occurred. 

Remarks 

If  a comma  or  semicolon  is  needed  in  the  setup  string,  the  escape  character  A can  be  used. 

Usage 

This  method  is  generally  called  from  within  an  override  of  the  wpSetup  method. 

How  to  Override 

This  method  is  generally  not  overridden. 

Related  Methods 

• wpcIsNew 

• wpSetup 

• WinCreateObject 
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wpScanSetupString  - 
WPObject  instance  method 


Example  Code 

If  NOMOVE  = YES  is  in  the  setup  string,  make  the  object  non-moveable. 

UCHAR  szValue[255]; 

ULONG  cbValue  = 255; 

if  ( wpScanSetupString  ( self,  pszSetup, 

"NOMOVE", 

szValue, 

ScbValue  ) ) { 

if  ( Istrcmpi  ( szValue,  "YES"  ) ) { 

_wpSetStyle  (self,  _wpQueryStyl e (self)  | 0BJSTYLE_N0M0VE) ; 

} ' 
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wpSetAssociationFilter  - 
WPProgram  instance  method 


#define  INCL_WINWORKPLACE 


BOOL  wpSetAssociationFilter  (WPProgram  * self,  PSZ  pszFiiter) 


The  wpSetAssociationFilter  instance  method  is  called  to  set  an  association  of  the  program  object  to  a 
data  file  object  based  on  a file  title  filter. 


Parameters 

seif  (WPProgram  *)  - input 
The  pointer  to  the  object. 
pszFiiter  (PSZ)  - input 

A pointer  to  a string  containing  file  title  filters  to  associate.  This  string  can  contain  several  file 
title  filters  separated  by  a comma.  Example:  pszFiiter  = “*.TXT,  *.DOC” 


Returns 

Success  indicator: 

TRUE  Successful  completion. 

FALSE  Error  occurred. 

Remarks 

The  association  filter  is  used  to  designate  this  program  as  an  available  open  view  for  data  file 
objects  which  have  a title  that  matches  one  of  the  association  filters  which  are  set.  If  a data  file 
object  matches  a filter  in  a program  object  or  program  file  object,  the  title  of  the  program  object  or 
program  file  object  will  appear  in  the  data  file  object's  Open  cascade  of  its  pop-up  menu.  A call  to 
the  wpSetAssociationFilter  method  will  cause  the  existing  association  filters  for  this  object  to  be 
replaced.  To  determine  the  existing  association  filters  that  are  set  on  this  object,  a call  to  the 
wpQueryAssociationFilter  method  can  be  made.  The  wpSetAssociationType  method  can  be  called  to 
set  an  association  based  on  the  type  of  data  file  object. 

Usage 

This  method  can  be  called  at  any  time  in  order  to  set  an  association  of  the  program  object  to  a data 
file  object  based  on  a file  title  filter. 


How  to  Override 

This  method  is  generally  not  overridden. 


Related  Methods 

• wpQueryAssociationType 

• wpSetAssociationFilter 

• wpSetAssociationType 
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wpSetAssociationFilter  - 
WPProgramFile  instance  method 


#define  INCL_WINWORKPLACE 


BOOL  wpSetAssociationFilter  (WPProgramFile  * self,  PSZ  pszFllter) 


The  wpSetAssociationFilter  instance  method  is  called  to  set  an  association  of  the  program  object  to  a 
data  file  object  based  on  a file  title  filter. 

Parameters 

self  (WPProgramFile  *)  - input 
The  pointer  to  the  object. 
pszFllter  (PSZ)  - input 

A pointer  to  a string  containing  file  title  filters  to  associate.  This  string  can  contain  several  file 
title  filters  separated  by  a comma. 

Example:  pszFilter  = “*.TXT,  *.DOC” 


Returns 

Success  indicator: 

TRUE  Successful  completion. 

FALSE  Error  occurred. 

Remarks 

The  association  filter  is  used  to  designate  this  program  as  an  available  open  view  for  data  file 
objects  which  have  a title  that  matches  one  of  the  association  filters  which  are  set.  If  a data  file 
object  matches  a filter  in  a program  object  or  program  file  object,  the  title  of  the  program  object  or 
program  file  object  will  appear  in  the  data  file  object's  Open  cascade  of  its  pop-up  menu.  A call  to 
the  wpSetAssociationFilter  method  will  cause  the  existing  association  filters  for  this  object  to  be 
replaced.  To  determine  the  existing  association  filters  that  are  set  on  this  object,  a call  to  the 
wpQueryAssociationFilter  method  can  be  made.  The  wpSetAssociationType  method  can  be  called  to 
set  an  association  based  on  the  type  of  data  file  object. 

Usage 

This  method  can  be  called  at  any  time  in  order  to  set  an  association  of  the  program  object  to  a data 
file  object  based  on  a file  title  filter. 


How  to  Override 

This  method  is  generally  not  overridden. 


Related  Methods 

• wpQueryAssociationType 

• wpSetAssociationType 
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wpSetAssociationType  - 
WPProgram  instance  method 


#define  INCL_WINWORKPLACE 


BOOL  wpSetAssociationType  (WPProgram  * self,  PSZ  pszType) 


The  wpSetAssociationType  instance  method  is  called  to  set  an  association  of  the  program  object  to  a 
data  file  object  based  on  a file  type. 

Parameters 

self  (WPProgram  *)  - input 
The  pointer  to  the  object. 
pszType  (PSZ)  - input 

A pointer  to  a string  containing  file  types  to  associate.  This  string  can  contain  several  file  types 
separated  by  a comma.  Example:  pszType  = "in  Text.C  Code” 


Returns 

Success  indicator: 

TRUE  Successful  completion. 

FALSE  Error  occurred. 

Remarks 

The  association  type  is  used  to  designate  this  program  as  an  available  open  view  for  data  file  objects 
which  have  a type  that  matches  one  of  the  association  types  which  are  set.  If  a data  file  object 
matches  a type  in  a program  object  or  program  file  object,  the  title  of  the  program  object  or  program 
file  object  will  appear  in  the  data  file  object's  Open  cascade  of  its  popup  menu.  A call  to  the 
wpSetAssociationType  method  will  cause  the  existing  association  types  for  this  object  to  be 
replaced.  To  determine  the  existing  association  type(s)  that  are  set  on  this  object,  a call  to  the 
wpQueryAssociationType  method  can  be  made.  The  wpSetAssociationFilter  method  can  be  called  to 
set  an  association  based  on  the  title  of  data  file  object. 

Usage 

This  method  can  be  called  at  any  time  in  order  to  set  an  association  of  the  program  object  to  a data 
file  object  based  on  a file  type. 


How  to  Override 

This  method  is  generally  not  overridden. 


Related  Methods 

• wpQueryAssociationType 

• wpSetAssociationFilter 

• wpSetAssociationType 
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wpSetAssociationType  - 
WPProgramFile  instance  method 


#define  INCL_WINWORKPLACE 


BOOL  wpSetAssociationType  (WPProgramFile  * self,  PSZ  pszType) 


The  wpSetAssociationType  instance  method  is  called  to  set  an  association  of  the  program  object  to  a 
data  file  object  based  on  a file  type. 


Parameters 

self  (WPProgramFile  *)  - input 
The  pointer  to  the  object. 
pszType  (PSZ)  - input 

A pointer  to  a string  containing  file  types  to  associate.  This  string  can  contain  several  file  types 
separated  by  a comma. 

Example:  pszType  = “Plain  Text, C Code” 


Returns 

Success  indicator: 

TRUE  Successful  completion. 

FALSE  Error  occurred. 

Remarks 

The  association  type  is  used  to  designate  this  program  as  an  available  open  view  for  data  file  objects 
which  have  a type  that  matches  one  of  the  association  types  which  are  set.  If  a data  file  object 
matches  a type  in  a program  object  or  program  file  object,  the  title  of  the  program  object  or  program 
file  object  will  appear  in  the  data  file  object's  Open  cascade  of  its  popup  menu.  A call  to  the 
wpSetAssociationType  method  will  cause  the  existing  association  types  for  this  object  to  be 
replaced.  To  determine  the  existing  association  types  that  are  set  on  this  object,  a call  to  the 
wpQueryAssociationType  method  can  be  made.  The  wpSetAssociationFilter  method  can  be  called  to 
set  an  association  based  on  the  title  of  data  file  object. 

Usage 

This  method  can  be  called  at  any  time  in  order  to  set  an  association  of  the  program  object  to  a data 
file  object  based  on  a file  type. 


How  to  Override 

This  method  is  generally  not  overridden. 

Related  Methods 

• wpQueryAssociationType 

• wpSetAssociationFilter 
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wpSetComputerName  - 
WPPrinter  instance  method 


#define  INCL_WINWORKPLACE 


BOOL  wpSetComputerName  (WPPrinter  * self,  PSZ  pszComputerName) 


The  wpSetComputerName  instance  method  is  called  to  set  the  name  of  the  computer  that  the  printer 
exists  on. 

Parameters 

self  (WPPrinter  *)  - input 

The  pointer  to  the  object  to  set  the  computer  name. 
pszComputerName  (PSZ)  - input 
The  computer  name  to  be  set. 


Returns 

Success  indicator: 

TRUE  Successful  completion 
FALSE  Error  occurred. 

How  to  Override 

This  method  is  generally  not  overridden. 

Related  Methods 

• wpQueryComputerName 

• wpSetPrinterName 


9-208  PM  Programming  Reference 


wpSetDefaultHelp  - 
WPObject  instance  method 


#define  INCL_WINWORKPLACE 


BOOL  wpSetDefaultHelp  (WPObject  * self,  ULONG  ulPanellD,  PSZ  pszHelpLibrary) 


The  wpSetDefaultHelp  Instance  method  is  called  to  set  the  default  help  panel  for  the  object. 

Parameters 

self  (WPObject  *)  - input 
The  pointer  to  the  object. 
ulPanellD  (ULONG)  - input 
The  help  panel  identity. 
pszHelpLibrary  (PSZ)  - input 

The  pointer  to  name  of  Help  Library.  A NULL  value  implies  the  default  should  be  used. 

Returns 

Success  indicator: 

TRUE  Successful  completion. 

FALSE  Error  occurred. 

Remarks 

The  default  help  panel  for  this  class  can  be  determined  by  calling  the  wpcIsQueryDefaultHelp 
method. 

Usage 

This  method  can  be  called  at  any  time  in  order  to  set  the  default  help  panel  for  this  object. 

How  to  Override 

This  method  is  generally  not  overridden. 

Related  Methods 

• wpDisplayHelp 

• wpMenultemHelpSelected 

• wpQueryDefaultHelp 

• wpcIsQueryDefaultHelp 
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wpSetDefaultPrinter  - 
WPPrinter  instance  method 


#define  INCL_WINWORKPLACE 


BOOL  wpSetDefaultPrinter  (WPPrinter  * self) 


The  wpSetDefaultPrinter  instance  method  is  called  to  set  a default  print  object. 

Parameters 

self  (WPPrinter  *)  - input 

The  pointer  to  the  object  to  be  the  default. 

Returns 

Success  indicator: 

TRUE  Successful  completion 
FALSE  Error  occurred. 

How  to  Override 

This  method  is  generally  not  overridden. 
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wpSetDefauItView  - 
WPObject  instance  method 


#define  INCL_WINWORKPLACE 


BOOL  wpSetDefauItView  (WPObject  * self,  ULONG  ulVIew) 


The  wpSetDefauItView  instance  method  is  called  to  allow  an  object  to  change  its  current  default  open 
view. 


Parameters 

self  (WPObject  *)  - input 


The  pointer  to  this  object. 
ulVIew  (ULONG)  - input 


Specifies  which  view  to  open. 


OPEN_CONTENTS 

OPENDEFAULT 

OPENDETAILS 

OPEN_HELP 

OPENRUNNING 

OPEN_SETTINGS 

OPENTREE 

OPENUSER 


Open  content  view. 

Open  default  view  (same  as  double-click). 

Open  details  view. 

Display  HelpPanel. 

Execute  object. 

Open  settings  notebook. 

Open  tree  view. 

Class  specific  views  have  a greater  value  than  this. 


Returns 

Success  indicator: 

True  Successful  completion 
False  Error  occurred. 


Remarks 

The  default  open  view  for  this  class  can  be  determined  by  calling  the  wpcIsQueryDefauItView 
method. 


Usage 

This  method  can  be  called  at  any  time  in  order  to  set  the  default  open  view  for  this  object. 


How  to  Override 

This  method  is  generally  not  overridden. 


Related  Methods 

• wpQueryDefauItView 

• wpcIsQueryDefauItView 
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wpSetError  - 
WPObject  instance  method 


#define  INCL_WINWORKPLACE 


BOOL  wpSetError  (WPObject  * self,  ULONG  ulErrorlD) 


The  wpSetError  instance  method  is  called  to  identify  an  error  condition. 

Parameters 

self  (WPObject  *)  - input 
The  pointer  to  the  object. 
ulErrorlD  (ULONG)  - input 

An  error  identity.  Refer  to  the  wpQueryError  method  for  information  about  this  value. 

Returns 

Success  indicator. 

TRUE  Successful  completion. 

FALSE  Error  occurred. 

Remarks 

The  wpSetError  method  will  set  the  last  error  on  an  object.  The  error  identity  is  retrievable  by 
issuing  a call  to  the  wpQueryError  method. 

Usage 

This  method  can  be  called  at  any  time  in  order  to  identify  an  error  condition.  This  method  is  typically 
called  prior  to  returning  unsuccessfully  from  a method. 

How  to  Override 

This  method  is  generally  not  overridden. 

Related  Methods 

• wpQueryError 
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wpSetFIdrAttr  - 
WPFolder  instance  method 


#define  INCL_WINWORKPLACE 


BOOL  wpSetFIdrAttr  (WPFolder  * self,  ULONG  ulAttr,  ULONG  uiVlew) 


The  wpSetFIdrAttr  instance  method  is  called  to  allow  the  folder  to  change  its  current  view  attributes. 

Parameters 

self  (WPFolder  *)  - input 
The  pointer  to  this  object. 
ulAttr  (ULONG)  - input 

A flag  indicating  the  object's  attributes.  These  are  the  CV_*  attributes  defined  by  the  Container 
Control  Window.  See  CNRINFO  on  page  A-15  for  detailed  description. 

uiVlew  (ULONG)  - input 

A flag  indicating  an  object's  open  view. 

OPEN_CONTENTS  Open  content  view. 

OPEN_DETAILS  Open  details  view. 

OPEN_TREE  Open  tree  view. 

Returns 

Success  indicator: 

TRUE  Successful  completion 
FALSE  Error  occurred. 

Remarks 

The  flags  should  be  valid  for  the  specified  view.  For  example,  CV  TREE  should  not  be  specified  for 
details  view. 

Usage 

This  method  can  be  called  at  any  time  in  order  to  set  the  view  attributes. 


How  to  Override 

This  method  is  generally  not  overridden. 


Related  Methods 

• wpQueryFIdrAttr 

• wpQueryFIdrFlags 

• wpQueryFIdrFont 

• wpSetFIdrFlags 

• wpSetFIdrFont 
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wpSetFIdrDetailsClass  - 
WPFolder  instance  method 


#define  INCL_WINWORKPLACE 


BOOL  wpSetFIdrDetailsClass  (WPFolder  * self,  M_WPObject  * Class) 


The  wpSetFIdrDetailsClass  instance  method  is  called  to  set  the  class  for  which  details  in  the  folder 
will  be  displayed. 

Parameters 

self  (WPFolder  *)  - input 
The  pointer  to  the  object. 

Class  (M_WPObject  *)  - input 

The  pointer  to  the  class  object  for  which  details  are  to  be  displayed. 


Returns 

Success  indicator. 

TRUE  Successful  completion. 

FALSE  Error  occurred. 

Remarks 

Since  folders  can  contain  objects  of  different  classes  which  can  have  different  details,  it  is  often 
necessary  for  the  user  to  specify  which  class  of  details  to  be  displayed.  The  value  set  by  this  method 
is  not  used  until  a details  view  of  the  folder  is  opened.  The  wpQueryFIdrDetailsClass  method  can  be 
called  to  determine  the  class  of  details  currently  set.  All  column  visibility  states  are  reset  by  this 
method. 

Usage 

This  method  can  be  called  at  any  time  in  order  to  set  the  current  class  of  details  to  be  displayed. 


How  to  Override 

This  method  is  generally  not  overridden. 


Related  Methods 

• wpQueryFIdrDetailsClass 
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wpSetFIdrFlags  - 
WPFolder  instance  method 


#define  1NCL_WINW0RKPLACE 


BOOL  wpSetFIdrFlags  (WPFolder  * self,  ULONG  ulFlags) 


The  wpSetFIdrFlags  instance  method  is  called  to  allow  the  folder  to  change  its  current  flags. 

Parameters 

self  (WPFolder  *)  - input 

The  pointer  to  this  object. 

ulFlags  (ULONG)  - input 
The  folder  flags  to  be  set 

FOI_POPULATEOWITHALL  This  flag  is  set  if  the  folder  was  populated  with  all  its 

contents. 

FOI_POPULATEDWITHFOLDERS  This  flag  is  set  if  the  folder  was  populated  only  with  folders 

that  it  contains. 

FOI_WORKAREA  This  flag  is  set  if  the  user  sets  the  workarea  property. 

Returns 

Success  indicator: 

TRUE  Successful  completion 
FALSE  Error  occurred. 

Usage 

This  method  can  be  called  at  any  time  in  order  to  set  a folder's  flag. 

How  to  Override 

This  method  is  generally  not  overridden. 

Related  Methods 

• wpQueryFIdrAttr 

• wpQueryFIdrFlags 

• wpQueryFIdrFont 

• wpSetFIdrAttr 

• wpSetFIdrFont 


Chapter  9.  Workplace  Classes,  Instance  Methods,  and  Class  Methods  9-215 


wpSetFIdrFont  - 
WPFolder  instance  method 


The  wpSetFIdrFont  instance  method  is  called  to  allow  the  folder  to  change  its  current  font. 

Parameters 

self  (WPFolder  *)  - input 
The  pointer  to  this  object. 
pszFont(PSZ)  - input 

A pointer  to  a buffer  containing  the  font  name. 

If  pszFont  is  NULL,  the  font  presentation  parameter  will  be  set  back  to  the  default  font.  If  a 
pointer  to  a NULL  string  is  passed,  the  font  presentation  parameter  will  be  set  to  the  currently 
defined  font. 

ulVIew  (ULONG)  - input 

A flag  indicating  an  object's  open  view. 

OPEN_CONTENTS  Open  content  view. 

OPEN_DETAILS  Open  details  view. 

OPEN_TREE  Open  tree  view. 

Returns 

Success  indicator: 

TRUE  Successful  completion 
FALSE  Error  occurred. 

Remarks 

The  font  name  should  be  a valid  presentation  parameter  string. 

Usage 

This  method  can  be  called  at  any  time  in  order  to  change  the  current  font  for  a view. 

How  to  Override 

This  method  is  generally  not  overridden. 
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wpSetlcon  - 

WPObject  instance  method 


#define  INCL.WINWORKPLACE 


BOOL  wpSetlcon  (WPObject  * self,  HPOINTER  hptrNewIcon) 


The  wpSetlcon  instance  method  is  called  to  allow  the  object  to  set  its  current  icon. 

Parameters 

self  (WPObject  *)  - input 
The  pointer  to  this  object. 
hptrNewIcon  (HPOINTER)  - input 
A pointer  to  the  object  handle. 

Returns 

Success  indicator: 

TRUE  Successful  completion 
FALSE  Error  occurred. 

Remarks 

If  the  OBJSTYLE_NOTDEFAULTICON  style  is  currently  set  for  the  object,  the  object's  icon  will  be 
destroyed  if  the  object  is  destroyed  or  made  dormant. 

Usage 

This  method  can  be  called  at  any  time  in  order  to  change  the  visible  icon  for  this  object.  To 
permanently  change  the  icon,  the  wpSetlconData  method  should  be  called. 


How  to  Override 

This  method  is  generally  not  overridden. 


Related  Methods 

• wpcisQuerylcon 

• wpQuerylcon 

• wpQuerylconData 

• wpSetlconData 
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wpSetlconData  - 
WPObject  instance  method 


#define  INCL_WINWORKPLACE 


BOOL  wpSetlconData  (WPObject  * self,  PICONINFO  pplconlnfo) 


The  wpSetlconData  instance  method  is  called  to  allow  the  object  to  permanently  set  its  current  icon. 

Parameters 

self  (WPObject  *)  - input 
The  pointer  to  this  object, 
pplconlnfo  (PICONINFO)  - input 

A pointer  to  an  ICONINFO  structure  containing  an  icon  specification. 

Returns 

Success  indicator: 

True  Successful  completion 
False  Error  occurred. 

Usage 

This  method  can  be  called  at  any  time  in  order  to  permanently  change  the  icon  for  this  object.  To 
temporarily  change  or  refresh  the  icon  for  this  object,  the  wpSetlcon  method  should  be  called. 

How  to  Override 

This  method  is  generally  not  overridden. 

Related  Methods 

• wpcIsQuerylcon 

• wpQuerylcon 

• wpQuerylconData 

• wpSetlcon 


9-218  PM  Programming  Reference 


wpSetNextlconPos  - 
WPFolder  instance  method 


#define  INCL_WINWORKPLACE 


BOOL  wpSetNextlconPos  (WPFolder  * self,  PPOINTL  pptl) 


The  wpSetNextlconPos  instance  method  is  called  to  allow  the  folder  to  change  the  next  icon  position. 

Parameters 

self  (WPFolder  *)  - input 
The  pointer  to  this  object, 
pptl  (PPOINTL)  - input 

The  position  within  the  folder. 

Returns 

Success  indicator: 

TRUE  Successful  completion 
FALSE  Error  occurred. 

Remarks 

The  next  icon  position  is  typically  set  during  a drag  or  drop  operation  in  order  to  ensure  that  the 
items  dropped  into  a folder  are  located  where  the  user  wanted  them. 

Usage 

This  method  can  be  called  at  any  time  in  order  to  set  the  next  icon  position  at  which  objects  will  be 
inserted  in  the  folder.  If  this  method  is  used,  the  previous  next  position  should  be  queried  and 
restored  afterwards. 

How  to  Override 

This  method  is  generally  not  overridden. 

Related  Methods 

• wpQueryNextlconPos 
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wpSetPalettelnfo  - 
WPPalette  instance  method 


#define  INCL_WINWORKPLACE 


BOOL  wpSetPalettelnfo  (WPPalette  * self,  PPALINFO  pPallnfo) 


The  wpSetPalettelnfo  instance  method  is  called  to  set  palette  information. 

Parameters 

self  (WPPalette  *)  - input 
The  pointer  to  the  object. 
pPallnfo  (PPALINFO)  - input 

A pointer  to  a PALINFO  structure. 

Returns 

Success  indicator. 

TRUE  Successful  completion. 

FALSE  Error  occurred. 

Remarks 

The  palette  information  can  be  retrieved  by  issuing  a call  to  wpQueryPalettelnfo. 

Usage 

This  method  can  be  called  at  any  time  in  order  to  set  the  palette  information. 

How  to  Override 

This  method  is  generally  not  overridden. 

Related  Methods 

• wpQueryPalettelnfo 
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wpSetPrinterName  - 
WPPrinter  instance  method 


#define  INCL_WINWORKPLACE 


BOOL  wpSetPrinterName  (WPPrinter  * self,  PSZ  pszPrinterName) 


The  wpSetPrinterName  instance  method  is  called  to  set  the  name  of  the  printer. 

Parameters 

self  (WPPrinter  *)  - input 

The  pointer  to  the  object  to  set  the  printer  name. 
pszPrinterName  (PSZ)  - input 
The  printer  name  to  be  set. 

Returns 

Success  indicator: 

TRUE  Successful  completion 
FALSE  Error  occurred. 

How  to  Override 

This  method  is  generally  not  overridden. 

Related  Methods 

• wpQueryPrinterName 

• wpSetComputerName 
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wpSetProgDetails  - 
WPProgram  instance  method 


#define  INCLWINWORKPLACE 


BOOL  wpSetProgDetails  (WPProgram  * self,  PPROGDETAILS  pProgDetalls) 


The  wpSetProgDetails  instance  method  is  called  to  allow  the  object  to  change  its  program  details. 

Parameters 

self  (WPProgram  *)  - input 
The  pointer  to  this  object. 
pProgDetalls  (PPROGDETAILS)  - input 
The  pointer  to  the  program  details. 

Returns 

Success  indicator: 

TRUE  Successful  completion 
FALSE  Error  occurred. 

Usage 

This  method  can  be  called  at  any  time  in  order  to  set  the  details  for  this  object. 

How  to  Override 

This  method  is  generally  not  overridden. 

Related  Methods 

• wpQueryProgDetails 
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wpSetProgDetails  - 
WPProgramFile  instance  method 


#define  INCL_WINWORKPLACE 


BOOL  wpSetProgDetails  (WPProgramFile  * self,  PPROGDETAILS  pProgDetails) 


The  wpSetProgDetails  instance  method  is  called  to  allow  the  object  to  change  its  program  details. 

Parameters 

self  (WPProgramFile  *)  - input 
The  pointer  to  this  object. 
pProgDetails  (PPROGDETAILS)  - input 
The  pointer  to  the  program  details. 

Returns 

Success  indicator: 

TRUE  Successful  completion 
FALSE  Error  occurred. 

Usage 

This  method  can  be  called  at  any  time  in  order  to  set  the  details  for  this  object. 

How  to  Override 

This  method  is  generally  not  overridden. 

Related  Methods 

• wpQueryProgDetails 
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wpSetRealName  - 

WP  File  System  instance  method 


#define  INCL_WINWORKPLACE 


BOOL  wpSetRealName  (WPObject  * seif,  PSZ  pszFllename) 


The  wpSetRealName  instance  method  will  set  the  physical  name  of  a file  system  object. 

Parameters 

self  (WPObject  *)  - input 
The  pointer  to  the  object. 
pszFllename  (PSZ)  - input 

A pointer  to  a new  filename.  This  file  can  not  be  fully  qualified. 


Returns 

Success  indicator. 

TRUE  Successful  completion. 

FALSE  Error  occurred. 

Remarks 

In  most  cases,  the  file  system  object's  real  name  and  title  are  identical.  When  a title  is  set  that  the 
file  system  containing  the  object  cannot  handle,  the  real  name  is  different.  In  this  situation,  real 
name  is  set  to  be  a truncated  title.  In  the  case  where  the  real  name  and  the  title  are  different,  the 
title  is  stored  in  the  file's  “.LONGNAME”  extended  attribute. 

Usage 

This  method  can  be  called  at  any  time  in  order  to  set  the  physical  name  for  a file  system  object. 

How  to  Override 

This  method  is  generally  not  overridden. 

Related  Methods 

• wpQueryRealName 
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wpSetShadowTitle  - 
WPShadow  instance  method 


#define  INCL_WINWORKPLACE 


BOOL  wpSetShadowTitle  (WPShadow  * self,  PSZ  pszTitle) 


The  wpSetShadowTitle  instance  method  is  called  to  set  the  title  on  the  shadow  without  affecting  the 
title  on  the  object  it  is  shadowing. 

Parameters 

self  (WPShadow  *)  - input 
The  pointer  to  the  object. 
pszTitle  (PSZ)  - input 
A pointer  to  a title. 

Returns 

Success  indicator. 

TRUE  Successful  completion. 

FALSE  Error  occurred. 

Usage 

This  method  can  be  called  at  any  time  in  order  to  set  a title  on  a shadow  object  without  affecting  the 
title  on  the  object  it  is  shadowing. 

How  to  Override 

This  method  is  generally  not  overridden. 

Related  Methods 

• wpSetTitle 
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wpSetStyle  - 
WPObject  instance  method 


#define  INCL_WINWORKPLACE 


BOOL  wpSetStyle  (WPObject  * self,  ULONG  ulNewStyle) 


The  wpSetStyle  instance  method  is  called  to  allow  an  object  to  set  its  current  object  style. 


Parameters 

self  (WPObject  *)  - input 

The  pointer  to  this  object. 

ulNewStyle  (ULONG)  - input 

OBJSTYLE_NOCOPY 

OBJSTYLENODELETE 

OBJSTYLENODRAG 

OBJSTYLENOSHADOW 

OBJSTYLENOMOVE 

OBJSTYLENOPRINT 

OBJSTYLENOTDEFAULTICON 

OBJ  STYLE_TEM  P LATE 

OBJSTYLENOTVISIBLE 

OBJSTYLENORENAME 

Returns 

Success  indicator: 

TRUE  Successful  completion 
FALSE  Error  occurred. 


Cannot  be  copied. 

Cannot  be  deleted. 

Cannot  be  dragged. 

Cannot  have  shadow  created. 

Cannot  move. 

Cannot  be  printed. 

Destroy  icon  when  object  goes  dormant 
This  object  is  a template. 

This  object  is  not  visible. 

Cannot  be  renamed. 


Usage 

This  method  can  be  called  at  any  time  in  order  to  change  an  object's  style. 


How  to  Override 

This  method  is  generally  not  overridden. 


Related  Methods 

• wpcisQueryStyle 

• wpQueryStyle 
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wpSetTitle  - 
WPObject  instance  method 


#define  INCL_WINWORKPLACE 
BOOL  wpSetTitle  (WPObject  * self,  PSZ  pszNewTitle) 

The  wpSetTitle  instance  method  is  called  to  allow  the  object  to  set  its  current  title. 

Parameters 

self  (WPObject  *)  - input 
The  pointer  to  this  object. 
pszNewTitle  (PSZ)  - input 

A pointer  to  a zero  terminated  string  which  contains  the  title  of  the  object. 

Returns 

Success  indicator: 

TRUE  Successful  completion 
FALSE  Error  occurred. 

Remarks 

Valid  titles  must  be  less  than  CCHMAXPATHCOMP  characters  in  length  - currently  defined  as  256. 

Usage 

This  method  can  be  called  at  any  time  in  order  to  set  an  object's  title. 

How  to  Override 

This  method  is  generally  not  overridden. 

Related  Methods 

• wpQueryTitle 

• wpcIsQueryTitle 
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wpSetType  - 

WPFileSystem  instance  method 


#define  INCL_WINWORKPLACE 


BOOL  wpSetType  (WPFileSystem  * self,  PSZ  pszTypes) 


The  wpSetType  instance  method  is  called  to  allow  the  object  to  change  the  type  of  its  file. 

Parameters 

self  (WPFileSystem  *)  - input 
The  pointer  to  this  object. 
pszTypes  (PSZ)  - input 

Pointer  to  a buffer  containing  type  to  set.  This  string  can  contain  a list  of  types  delineated  by  a 
line  feed  character.  For  example,  psztypes  = "Plain  Text\nC  code". 

Returns 

Success  indicator: 

True  Successful  completion 
False  Error  occurred. 

Remarks 

This  method  will  cause  the  file's  .TYPE  extended  attribute  to  be  set. 

Usage 

This  method  can  be  called  at  any  time  in  order  to  set  the  type  on  the  file  object. 

How  to  Override 

This  method  is  generally  not  overridden. 
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wpSetup  - 

WPObject  instance  method 


#define  INCL_WINWORKPLACE 
BOOL  wpSetup  (WPObject  * self,  PSZ  pszSetupStrlng) 

The  wpSetup  instance  method  is  called  to  allow  the  newly  created  object  to  initialize  itself. 

Parameters 

self  (WPObject  *)  - input 
The  pointer  to  this  object. 
pszSetupStrlng  (PSZ)  - input 
The  pointer  to  setup  string. 


Returns 

Success  indicator: 

TRUE  Successful  completion 
FALSE  Error  occurred. 

Remarks 

If  wpSetup  returns  FALSE,  the  creation  of  the  object  is  terminated.  The  pszSetupString  contains  a 
series  of  “keyname=value”  pairs  separated  by  semicolons,  that  change  the  behavior  of  the  object. 
Each  object  class  defines  the  keynames  and  the  parameters  it  expects  to  see  immediately  following 
Note  that  all  parameters  have  safe  defaults,  so  it  is  never  required  to  pass  parameters  to  an  object. 
If  a comma  or  semicolon  is  needed  in  the  setup  string,  the  escape  character can  be  used. 

The  following  table  shows  the  keyname-value  pairs  supported  by  the  WPObject  class. 


KEYNAME 

VALUE 

Description 

TITLE 

Title 

This  sets  the  object's  title.  This  is 
equivalent  to  calling  the  wpSetTitle 
method. 

ICONFILE 

filename 

This  sets  the  object's  icon.  This  is 
equivalent  to  calling  the 
wpSetlconData  method. 

HELPPANEL 

id 

This  sets  the  object's  default  help 
panel.  This  is  equivalent  to  calling 
the  wpSetDefaultHelp  method. 

HELPLIBRARY 

filename 

This  sets  the  help  library. 

TEMPLATE 

YES 

This  sets  the  object's  template 
property.  This  is  equivalent  to 
calling  the  wpSetStyle  method  with  a 
style  of  OBJSTYLE_TEMPLATE. 

NO 

This  resets  the  object's  template 
property. 
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wpSetup  - 

WPObject  instance  method 


KEYNAME 

VALUE 

Description 

NODELETE 

YES 

This  sets  the  object's  no  delete 
property.  This  is  equivalent  to 
calling  the  wpSetStyie  method  with  a 
style  of  OBJSTYLE_NODELETE. 

NO 

This  resets  the  object's  no  delete 
property. 

NOCOPY 

YES 

This  sets  the  object's  no  copy 
property.  This  is  equivalent  to 
calling  the  wpSetStyie  method  with  a 
style  of  OBJSTYLE_NOCOPY. 

NO 

This  resets  the  object's  no  copy 
style. 

NOMOVE 

YES 

This  sets  the  object's  no  move 
property.  This  is  equivalent  to 
calling  the  wpSetStyie  method  with  a 
style  of  OBJSTYLE_NOMOVE. 

NO 

This  resets  the  object's  no  move 
property. 

NOSHADOW 

YES 

This  sets  the  object's  no  link 
property.  This  is  equivalent  to 
calling  the  wpSetStyie  method  with  a 
style  of  OBJSTYLE_NOSHADOW. 

NO 

This  resets  the  object's  no  link 
property. 

NOTVISIBLE 

YES 

This  sets  the  object's  not  visible 
property.  This  is  equivalent  to 
calling  the  wpSetStyie  method  with  a 
style  of  OBJSTYLE_NOTVISIBLE. 

NO 

This  resets  the  object's  not  visible 
property. 

NOPRINT 

YES 

This  sets  the  object's  no  print 
property.  This  is  equivalent  to 
calling  the  wpSetStyie  method  with  a 
style  of  OBJSTYLE_NOPRINT. 

NO 

This  resets  the  object's  no  print 
property. 

ICONRESOURCE 

id, module 

This  sets  the  object's  icon.  This  is 
equivalent  to  calling  the 
wpSetlconData  method,  'id'  is  the 
identity  of  an  icon  resource  in  the 
'module'  dynamic  link  library  (DLL). 

ICONPOS 

x,y 

This  sets  the  object's  initial  icon 
position.  The  x and  y values 
represent  the  position  in  the  object's 
folder  in  percentage  coordinates. 
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WPObject  instance  method 


KEYNAME 

VALUE 

Description 

OBJECTID 

<name> 

This  sets  the  object's  identity.  The 
object  id  will  stay  with  the  object 
even  if  it  is  moved  or  renamed.  The 
object  pointer  or  handle  can  be 
retrieved  via  the  wpcisQueryObject 
method  or  the  WinQueryObject 
function,  respectively.  An  object  id 
is  any  unique  string  preceded  with  a 
' < ' and  terminated  with  a ' > '. 

NORENAME 

YES 

This  sets  the  object's  no  rename 
property.  This  is  equivalent  to 
calling  the  wpSetStyle  method  with  a 
style  of  OBJSTYLE_NORENAME. 

NO 

This  resets  the  object's  no  rename 
property 

NODRAG 

YES 

This  sets  the  object's  no  drag 
property.  This  is  equivalent  to 
calling  the  wpSetStyle  method  with  a 
style  of  OBJSTYLE_NODRAG. 

NO 

This  resets  the  object's  no  drag 
property. 

VIEWBUTTON 

HIDE 

Views  of  this  object  will  have  a hide 
button  as  opposed  to  a minimize 
button. 

MINIMIZE 

Views  of  this  object  will  have  a 
minimize  button  as  opposed  to  a 
hide  button. 

MINWIN 

HIDE 

Views  of  this  object  will  hide  when 
their  minimize  button  is  selected. 

VIEWER 

Views  of  this  object  will  minimize  to 
the  minimized  window  viewer  when 
their  minimize  button  is  selected. 

DESKTOP 

Views  of  this  object  will  minimize  to 
the  Desktop  when  their  minimize 
button  is  selected. 

CONCURRENTVIEW 

YES 

New  views  of  this  object  will  be 
created  every  time  the  user  selects 
open. 

NO 

Open  views  of  this  object  will 
resurface  when  the  user  selects 
open. 

OPEN 

SETTINGS 

Open  settings  view  when  object  is 
created  or  when  WinSetObjectData 
is  called. 

DEFAULT 

Open  default  view  when  object  is 
created  or  when  WinSetObjectData 
is  called. 
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wpSetup  - 

WPObject  instance  method 

Usage 

This  method  is  generally  only  called  by  the  system  during  the  processing  of  wpcIsNew, 
WinCreateObject,  and  WinSetObjectData. 


How  to  Override 

This  method  is  overridden  by  classes  which  introduce  their  own  KEYNAMES. 


Related  Methods 

• WinCreateObject 

• wpcIsNew 

• WinSetObjectData 

• wpScanSetupString 

Example  Code 

pszSetupString="TITLE=MY0bject,IC0NFILE=myobj.ico,HELPPANEL=132, 
TEMPLATE=YES ,N0DELETE=N0" 

obj  = wpcIsNew  ( _WPDataFile, 

"My  new  file", 

pszSetupString, 

myfolder, 

FALSE  ); 
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wpSetupCell  - 
WPPalette  instance  method 


#define  INCL_WINWORKPLACE 


BOOL  wpSetupCell  (WPPalette  * self,  PVOIO  pCellData,  ULONG  ulcb,  ULONG  ulx, 
ULONG  uly) 


The  wpSetupCell  instance  method  is  called  to  initialize  a cell. 

Parameters 

self  (WPPalette  *)  - input 
The  pointer  to  the  object. 
pCellData  (PVOID)  - input 

A pointer  to  the  data  to  be  stored, 
ulcb  (ULONG)  - input 

The  size  of  the  data  to  be  stored., 
ulx  (ULONG)  - input 

X-coordinate  of  the  cell  to  be  setup, 
uly  (ULONG)  - input 

Y-coordinate  of  the  cell  to  be  setup. 

Returns 

Success  indicator. 

TRUE  Successful  completion. 

FALSE  Error  occurred. 

Usage 

This  method  can  be  called  at  any  time  in  order  to  initialize  a cell. 

How  to  Override 

This  method  is  generally  not  overridden. 
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wpShowPalettePointer  - 
WPPalette  instance  method 


#define  INCL_WINWORKPLACE 


BOOL  wpShowPalettePointer  (WPPalette  * somSelf) 


The  wpShowPalettePointer  instance  method  displays  the  applicator  pointer  for  the  palette. 

Parameters 

somSelf  (WPPalette  *)  - input 

The  pointer  to  the  instance  object. 


Returns 

TRUE  The  pointer  was  successfully  changed  to  the  applicator  symbol  for  this  palette. 

FALSE  The  pointer  was  not  successfully  changed  to  the  applicator  symbol  for  this  palette. 

Remarks 

To  provide  the  user  with  a visual  clue  to  the  purpose  of  a palette  window,  the  mouse  cursor  is  always 
changed  to  the  applicator  symbol  when  it  is  within  the  bounds  of  an  open  palette  view  window.  For 
example,  when  the  cursor  is  within  the  color  palette  window  it  displays  a paintbrush.  Note  that  this 
method  should  cause  just  the  applicator  to  be  displayed.  When  the  wpDragCell  method  Is  invoked, 
the  applicator  plus  the  attribute  should  be  shown  if  possible.  For  example,  the  paintbrush  used  in  the 
color  palette  appears  to  have  been  dipped  in  the  color  that  is  being  applied. 

Usage 

This  method  may  be  called  at  any  time,  however  it  is  unlikely  to  be  useful. 


How  to  Override 

All  subclasses  of  wpPalette  need  to  override  this  method  to  ensure  that  the  cursor  changes  to  an 
applicator  while  it  is  within  the  palette  window. 


Related  Methods 

• wpDragCell 
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wpStart  Job  Again  - 
WPJob  instance  method 


#define  INCL_WINWORKPLACE 


BOOL  wpStartJobAgaln  (WPJob  * self) 


The  wpStartJobAgain  instance  method  is  called  to  start  printing  a job  object  again. 

Parameters 

self  (WPJob  *)  - input 

The  pointer  to  the  object  to  be  re-started. 

Returns 

Success  indicator: 

TRUE  Successful  completion 
FALSE  Error  occurred. 

How  to  Override 

This  method  is  generally  not  overridden. 
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wpSwitchTo  - 
WPObject  instance  method 


#define  INCL_WINWORKPLACE 


BOOL  wpSwitchTo  (WPObject  * self,  ULONG  ulVIew) 


The  wpSwitchTo  instance  method  is  called  to  allow  the  object  to  give  focus  to  the  specified  open 
view. 


Parameters 

self  (WPObject  *)  - input 
The  pointer  to  this  object. 
ulVIew  (ULONG)  - input 


A flag  indicating  open  view  to  which  focus  is  to  be  given. 


OPEN_CONTENTS 

OPENDEFAULT 

OPENDETAILS 

OPENHELP 

OPENRUNNING 

OPEN_SETTINGS 

OPENTREE 

OPENUSER 


Open  content  view. 

Open  default  view  (same  as  double-click). 

Open  details  view. 

Display  HelpPanel. 

Execute  object. 

Open  settings  notebook. 

Open  tree  view. 

Class  specific  views  have  a greater  value  than  this. 


Returns 

Success  indicator: 

TRUE  Successful  completion 
FALSE  Error  occurred. 


Remarks 

The  focus  is  given  to  the  specified  open  view  of  the  object  if  it  exists.  This  is  done  by  scanning  the 
in-use  list. 


Usage 

This  method  can  be  called  at  any  time  in  order  to  switch  to  an  existing  view  of  this  object. 


How  to  Override 

This  method  is  generally  not  overridden. 


Related  Methods 

• wpOpen 


9-236  PM  Programming  Reference 


wpUnlockObject  - 
WPObject  instance  method 


#define  INCL_WINWORKPLACE 


BOOL  wpUnlockObject  (WPObject  * self) 


The  wpUnlockObject  instance  method  is  called  to  allow  an  object  to  go  into  the  dormant  state. 

Parameters 

self  (WPObject  *)  - input 
The  pointer  to  the  object. 


Returns 

Success  indicator: 

TRUE  Successful  completion. 

FALSE  Error  occurred. 

Remarks 

The  wpUnlockObject  method  will  unlock  the  specified  object.  When  an  object  is  unlocked,  it  will 
automatically  go  into  the  dormant  state  when  it  no  longer  has  open  views  and  the  container  it  is  in  is 
no  longer  open. 

Usage 

This  method  can  be  called  at  any  time  in  order  to  allow  the  object  to  go  into  the  dormant  state. 

This  method  is  used  in  conjunction  with  other  methods  which  create  new  instances  of  objects.  If 
these  methods  are  called  with  the  fLock  flag  set  to  TRUE,  the  new  object  will  be  locked  into  the 
awake  state  until  the  wpUnlockObject  method  is  called. 


How  to  Override 

This  method  is  generally  not  overridden. 


Related  Methods 

• wpcisCreateDefauItTemplates 

• wpQueryContent 

• wpCopyObject 

• wpcisNew 
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wpUnlnitData  - 
WPObject  instance  method 


#define  INCL_WINWORKPLACE 


VOID  wpUnlnitData  (WPObject  * self) 


The  wpUnlnitData  instance  method  is  called  to  allow  the  object  to  free  allocated  resources. 

Parameters 

self  (WPObject  *)  - input 
The  pointer  to  this  object. 


Returns 

The  return  value  is  VOID. 

Usage 

This  method  is  generally  only  called  by  the  system  when  the  object  is  made  dormant.  The  object  is 
made  dormant  when  it  is  destroyed  or  when  there  are  no  open  views  and  the  object  and  the  folder 
containing  the  object  is  not  open. 


How  to  Override 

This  method  is  overridden  to  deallocate  resources  allocated  during  the  processing  of  wpInitData. 


Related  Methods 

• wpInitData 
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Workplace  Class  Methods 

The  following  pages  contain  an  alphabetical  listing  of  the  Workplace  Class  methods. 
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wpcIsCreateDefauItT  emplates 
WPObject  class  method 


#define  INCL_WINWORKPLACE 


ULONG  wpcIsCreateDefauItT emplates  (M_WPObject  * self,  WPFolder  * Folder) 


The  wpcIsCreateDefauItTemplates  method  is  called  to  allow  the  specified  class  to  create  default 
template  instances  of  its  class. 

Parameters 

self  (M_WPObject  *)  - input 

The  pointer  to  the  class  object. 

Folder  (WPFolder  *)  - input 

A pointer  to  the  folder  in  which  to  create  the  templates. 


Returns 

Number  of  templates  created. 

Usage 

This  method  is  generally  only  called  by  the  system  when  the  class  is  registered.  A class  is 
registered  by  a call  to  the  WinRegisterObjectClass  function. 

When  the  system  calls  this  method,  “Folder"  is  a pointer  to  the  Templates  folder. 


How  to  Override 

This  method  should  be  overridden  by  classes  which  need  to  create  default  template  instances  of 
their  class. 
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wpcIsFindObjectEnd  - 
WPObject  class  method 


#define  INCL_WINWORKPLACE 


BOOL  wpcIsFindObjectEnd  (M_WPObject  * self,  HFIND  hflndflnd) 


The  wpcIsFindObjectEnd  method  is  called  to  end  the  find  operation  started  by  a call  to  the 
wpcIsFindObjectFirst  method. 

Parameters 

self  (M_WPObject  *)  - input 

The  pointer  to  the  class  object, 
hflndflnd  (HFIND)  - input 

The  handle  associated  with  a previous  wpcIsFindObjectFirst  or  wpcisFindObjectNext  method 
call. 

Returns 

Success  indicator. 

TRUE  Successful  completion. 

FALSE  Error  occurred. 

Usage 

This  method  should  be  called  to  terminate  a find  operation  that  was  started  by  a previous  call  to  the 
wpcIsFindObjectFirst  method. 

How  to  Override 

This  method  is  generally  not  overridden. 

Related  Methods 

• wpcIsFindObjectFirst 

• wpcisFindObjectNext 
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wpcIsFindObjectFirst  - 
WPObject  class  method 


#define  INCL_WINWORKPLACE 


BOOL  wpcIsFindObjectFirst  (M_WPOb]ect  * self,  PHFIND  pflnd,  PSZ  pszTitle, 

WPFolder  * Folder,  BOOL  fSubfolders,  PVOID  pExtendedCrlteria, 
POBJECTS  pBuf,  PULONG  pCount) 


The  wpcIsFindObjectFirst  method  is  called  to  find  workplace  objects. 

Parameters 

self  (M_WPObject  *)  - input 

The  pointer  to  the  class  object, 
pflnd  (PHFIND)  - output 

The  address  of  the  handle  associated  with  this  wpcIsFindObjectFirst  method.  This  handle  is 
used  with  subsequent  calls  to  wpcisFindObjectNext  and  wpcisFindObjectEnd. 

pszTitle  (PSZ)  - input 

The  pointer  to  the  title  specification  for  objects  to  be  searched. 

This  title  may  include  the  wildcard  characters  “*”  and  “?.” 

Folder  (WPFolder  *)  - input 

A pointer  to  the  folder  in  which  to  find  objects. 

This  pointer  can  be  determined  by  issuing  a call  to  the  wpcisQueryFolder  method. 

fSubfolders  (BOOL)  - input 
Scope  indicator. 

FALSE  Search  only  the  folder  specified  by  Folder. 

TRUE  Search  Folder  and  all  folders  in  its  tree. 

pExtendedCrlteria  (PVOID)  - input 

A pointer  to  a buffer  that  contains  the  class-specific  extended  search  criteria. 
pBuf  (POBJECTS)  - output 

A pointer  to  a buffer  that  contains  an  array  of  object  pointers. 

The  size  of  this  buffer  must  be  large  enough  to  hold  the  number  of  requested  entries  specified  by 
pulCount. 

pCount  (PULONG)  - input/output 

The  address  of  the  number  of  matching  entries  requested  in  pobjectsBuf.  On  return,  this  field 
contains  the  number  of  entries  placed  into  pobjectsBuf. 

Returns 

Success  indicator. 

TRUE  Successful  completion. 

FALSE  Error  occurred. 

FALSE  can  indicate: 

WPER  R_OB  J ECT_NOT_FOU  N D 
WPERR_BUFFER_OVERFLOW 
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Remarks 

wpcIsFindObjectFirst  returns  object  pointers  (up  to  the  number  requested  in  pulCount)  for  as  many 
objects  which  match  the  specifications,  and  which  fits  in  pobjectsBuf.  On  output,  pulCount  contains 
the  actual  number  of  object  pointers  returned. 

wpcIsFindObjectNext  uses  the  find  object  handle  associated  with  wpcIsFindObjectFirst  to  continue 
the  search  started  by  the  wpcIsFindObjectFirst  request. 

If  wpcIsFindObjectFirst  returns  FALSE,  the  wpQueryError  method  can  be  called  to  retrieve  the  error 
code.  Error  codes  include: 

WPERR_OBJECT_NOT_FOUND  No  objects  matching  the  specified  criteria  were  found. 
WPERR_BUFFER_OVERFLOW  The  pobjectsBuf  buffer  was  not  large  enough  to  fit  all  objects  matching 

the  specified  criteria.  The  wpcIsFindObjectNext  method  should  be 
called  to  retrieve  the  rest  of  the  objects  matching  the  specified 
criteria. 

The  wpcisFindObjectEnd  method  should  be  called  to  terminate  the  find  operation. 

Usage 

This  method  can  be  called  at  any  time  in  order  to  find  objects. 

How  to  Override 

This  method  is  generally  not  overridden. 


Related  Methods 

• wpcIsFindObjectNext 

• wpcisFindObjectEnd 
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wpcIsFindObjectNext  - 
WPObject  class  method 


#define  INCL_WINWORKPLACE 


BOOL  wpcIsFindObjectNext  (M_WPObject  * self,  HFIND  hflndflnd,  POBJECTS  pBuf, 

PULONG  pCount) 


The  wpcIsFindObjectNext  method  is  called  to  find  the  next  set  of  matching  objects. 

Parameters 

self  (M_WPObject  *)  - input 

The  pointer  to  the  class  object, 
hflndflnd  (HFIND)  - input 

The  handle  associated  with  a previous  wpcIsFindObjectFirst  or  wpcIsFindObjectNext  method 
call. 

pBuf  (POBJECTS)  - output 

A pointer  to  a buffer  that  contains  an  array  of  object  pointers. 

The  size  of  this  buffer  must  be  large  enough  to  hold  the  number  of  requested  entries  specified  by 
pulCount. 

pCount  (PULONG)  - input/output 

Address  of  the  number  of  matching  entries  requested  in  pobjectsBuf.  On  return,  this  field 
contains  the  number  of  entries  placed  into  pobjectsBuf. 

Returns 

Success  indicator. 

TRUE  Successful  completion. 

FALSE  Error  occurred. 

FALSE  can  indicate: 

WPERR_OBJECT_NOT_FOUND 

WPERR_BUFFER_OVERFLOW 


Remarks 

wpcIsFindObjectNext  returns  object  pointers  (up  to  the  number  requested  in  pulCount)  for  as  many 
objects  which  match  the  specifications,  and  which  fits  in  pobjectsBuf.  On  output,  pulCount  contains 
the  actual  number  of  object  pointers  returned. 

wpcIsFindObjectNext  uses  the  find  object  handle  associated  with  wpcIsFindObjectFirst  to  continue 
the  search  started  by  the  wpcIsFindObjectFirst  request. 

If  wpcIsFindObjectNext  returns  FALSE,  the  wpQueryError  method  can  be  called  to  retrieve  the  error 
code.  Error  codes  include: 

WPERR_OBJECT_NOT_FOUND  No  objects  matching  the  specified  criteria  were  found. 
WPERR_BUFFER_OVERFLOW  The  pobjectsBuf  buffer  was  not  large  enough  to  fit  all  objects  matching 

the  specified  criteria.  The  wpcIsFindObjectNext  method  should  be 
called  to  retrieve  the  rest  of  the  objects  matching  the  specified 
criteria. 

The  wpcisFindObjectEnd  method  should  be  called  to  terminate  the  find  operation. 
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Usage 

This  method  can  be  called  at  any  time  in  order  to  find  the  next  set  of  matching  objects.  This  method 
should  only  be  called  after  a previous  call  to  the  wpcIsFindObjectFirst  method  returned  an  error  of 
WPERR_BUFFER_OVERFLOW. 

How  to  Override 

This  method  is  generally  not  overridden. 


Related  Methods 

• wpcIsFindObjectFirst 

• wpcisFindObjectEnd 


Chapter  9.  Workplace  Classes,  Instance  Methods,  and  Class  Methods  9-245 


wpcIsInitData  - 
WPObject  class  method 


#define  INCL_WINWORKPLACE 


VOID  wpcIsInitData  (MWPObject  * self) 


The  wpcIsInitData  method  Is  called  to  allow  the  class  object  to  Initialize  its  instance  data. 


Parameters 

self  (MWPObject  *)  - input 

The  pointer  to  the  class  object. 


Returns 

The  return  value  is  VOID. 

Remarks 

This  method  will  be  called  immediately  after  the  class  object  is  first  awakened.  When  the  class 
object  is  made  dormant,  the  wpcIslInlnitData  method  is  called  to  give  the  class  object  the  opportunity 
to  deallocate  resources  allocated  during  the  processing  of  wpcIsInitData. 

Usage 

This  method  is  generally  only  called  by  the  system  when  the  class  object  is  awakened.  The  class 
object  is  awakened  when  the  first  instance  of  this  class  is  either  awakened  or  newly  created.  It  is 
made  dormant  again  when  the  last  Instance  of  this  class  is  made  dormant. 


How  to  Override 

Any  class  that  has  metaclass  instance  variables  should  override  this  method  so  that  those  variables 
are  all  initially  in  a known  state.  It  is  essential  to  pass  this  method  onto  the  parent  class  object 
before  performing  any  override  processing. 


Related  Methods 

• wpcIslInlnitData 
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#define  INCL_WINWORKPLACE 


WPObject  * wpcIsMakeAwake  (M_WPObject  * self,  PSZ  pszTItle,  ULONG  ulStyle, 

HPOINTER  hptrlcon,  POBJDATA  pObjOata,  WPFolder  * Folder, 
ULONG  ulUser) 


The  wpcIsMakeAwake  method  is  called  to  allow  the  specified  class  to  awaken  an  object. 


Parameters 

self  (M_WPObject  *)  - input 

The  pointer  to  the  class  object. 
pszTItle  (PSZ)  - input 

A pointer  to  a string  containing  a title  to  set  on  the  object.  If  this  value  is  NULL,  the  class  default 
value  will  be  used. 

ulStyle  (ULONG)  - input 

The  object  style  flags  to  set  on  the  object.  If  this  value  is  NULL,  the  current  or  default  value  will 
be  used. 


Predefined  object  style  bits  are  as  follows: 


OBJSTYLE_NOCOPY 

OBJSTYLENODELETE 

OBJSTYLE  NODDRAG 

OBJSTYLENOLINK 

OBJSTYLENOMOVE 

OBJSTYLENOPRINT 

OBJSTYLENOTDEFAULTICON 

OBJSTYLENOTVISIBLE 

OBJSTYLETEMPLATE 

hptrlcon  (HPOINTER)  - input 


Do  not  allow  copy  on  the  object. 

Do  not  allow  delete  on  the  object. 

Do  not  allow  drag  of  this  object. 

Do  not  allow  link  on  the  object. 

Do  not  allow  move  on  the  object. 

Do  not  allow  print  of  this  object. 

Destroy  icon  when  object  goes  to  sleep. 
Make  this  object  hidden. 

This  object  is  a template. 


The  icon  to  set  on  the  object.  If  this  value  is  NULL,  the  class  default  value  will  be  used. 
pObjData  (POBJDATA)  - input 

A pointer  to  the  object  data.  If  this  value  is  NULL,  the  class  default  value  will  be  used. 


Folder  (WPFolder  *)  - input 

A pointer  to  a folder  object  which  contains  the  new  object.  This  pointer  can  be  determined  by 
issuing  a call  to  the  wpcisQueryFolder  method. 


ulUser  (ULONG)  - input 

This  value  is  defined  by  the  user  and  used  by  the  base  storage  class. 


Returns 

Success  indicator: 

NULL  Error  occurred. 

Other  Pointer  to  the  awakened  object. 
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wpcIsMakeAwake  - 
WPObject  class  method 


Remarks 

An  object  is  made  awake  when  it  is  created  in  an  open  folder  or  when  a folder  containing  the  object 
is  opened.  An  object  awakened  by  the  wpcIsMakeAwake  class  method  is  automatically  locked.  The 
wpUnlockObject  method  can  be  called  to  allow  the  object  to  return  to  its  dormant  state. 

Usage 

This  method  is  generally  called  only  by  base  storage  classes  in  order  to  awaken  an  object  from  the 
dormant  state. 

How  to  Override 

This  method  is  generally  not  overridden. 


Related  Methods 

• wpcIsNew 

• wpInitData 

• wpUnlockObject 
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wpcIsNew  - 
WPObject  class  method 


#define  INCL_WINWORKPLACE 


WPObject  * wpcIsNew  (MWPObject  * self,  PSZ  pszTitle,  PSZ  pszSetupEnv, 
WPFolder  * Folder,  BOOL  fLock) 


The  wpcIsNew  method  is  called  to  make  an  new  Instance  of  this  class  of  object. 


Parameters 

self  (M_WPObject  *)  - input 

The  pointer  to  the  class  in  which  a new  instance  is  to  be  created. 
pszTitle  (PSZ)  - input 

A pointer  to  a zero-terminated  string  which  contains  the  initial  title  of  the  object  as  it  is  to  appear 
when  displayed  on  the  user  interface  underneath  an  icon  or  on  the  title  bar  of  an  open  object. 

pszSetupEnv  (PSZ)  - input 

A pointer  to  a zero  terminated  string  which  contains  the  object-specific  parameters  to  the  new 
object.  Refer  to  wpSetup  for  the  description  of  this  field  for  the  class  of  object  being  created. 

The  pszSetupEnv  string  is  extracted  when  the  wpSetup  method  is  called. 

Folder  (WPFolder  *)  - input 

A pointer  to  a Folder  object  in  which  to  place  this  new  object.  This  pointer  can  be  determined  by 
issuing  a call  to  the  wpcIsQueryFolder  method. 

fLock  (BOOL)  - input 
The  lock  object  flag. 

If  this  flag  Is  false,  the  newly  created  object  will  be  made  dormant  whenever  the  object  and  the 
folder  containing  the  object  are  closed.  If  this  flag  is  true,  the  new  flag  will  remain  awake  until 
the  caller  Issues  the  wpUnlockObject  method  on  it. 


Returns 

Success  indicator: 

NULL  Error  occurred. 

Other  A pointer  to  the  new  object  created. 

Remarks 

This  method  is  a modified  version  of  somNew  that  takes  arguments.  These  arguments  provide  a way 
to  create  a new  object  with  a defined  state. 

Usage 

This  method  can  be  called  at  any  time  in  order  to  create  a new  workplace  object.  The  created  object 
is  a persistent  instance  of  the  class  specified  by  WPCIass. 


How  to  Override 

This  method  is  generally  not  overridden. 
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Related  Methods 

• wpFree 

• wpcIsQueryFolder 

• wpUnlockObject 

• wpSetup 
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WPObject  class  method 


#define  INCL_WINWORKPLACE 


ULONG  wpcIsQueryDefaultHelp  (M_  WPObject  * self,  PULONG  pHelpPanelld, 

PSZ  pszHelpLIbrary) 


The  wpcIsQueryDefaultHelp  method  Is  called  to  allow  the  class  object  to  specify  Its  default  help 
panel  for  Its  instances. 

Parameters 

self  (M_WPObject  *)  - input 

The  pointer  to  the  class  object. 
pHelpPanelld  (PULONG)  - output 
The  pointer  to  the  help  panel  id. 
pszHelpLIbrary  (PSZ)  - output 

The  pointer  to  the  buffer  in  which  to  place  the  name  of  help  library.  This  buffer  should  be  at 
least  the  length  of  CCHMAXPATH  bytes. 

Returns 

Success  indicator: 

TRUE  Successful  completion 
FALSE  Error  occurred. 

Remarks 

This  class  method  is  called  during  the  default  processing  of  wpQueryDefaultHelp. 

Usage 

This  method  can  be  called  at  any  time  in  order  to  determine  the  default  help  panel  for  this  object 
class. 

How  to  Override 

The  default  WPObject  class  does  not  process  this  method  other  than  returning  FALSE. 


Related  Methods 

• wpDisplayHelp 

• wpMenultemHelpSelected 

• wpQueryDefaultHelp 

• wpSetDefaultHelp 
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WPObject  class  method 


#define  INCL_WINWORKPLACE 


ULONG  wpcIsQueryOefauItVIew  (M  WPObject  * self) 


The  wpcIsQueryDefauItView  method  is  called  to  allow  the  class  object  to  specify  the  default  open 
view  for  its  instance. 


Parameters 

self  (M_WPObject  *)  - input 

The  pointer  to  the  class  object. 


Returns 

Default  open  view. 

OPEN_CONTENTS 

OPENDEFAULT 

OPENDETAILS 

OPENHELP 

OPENRUNNING 

OPEN_SETTINGS 

OPENTREE 

OPENUNKNOWN 

OPENUSER 


Open  content  view. 

Open  default  view  (same  as  double-click). 

Open  details  view. 

Display  HelpPanel. 

Execute  object. 

Open  settings  notebook. 

Open  tree  view. 

Unknown  view. 

Class  specific  views  have  a greater  value  than  this. 


Usage 

This  method  can  be  called  at  any  time  in  order  to  query  the  default  open  view  for  instances  of  this 
class. 


How  to  Override 

All  classes  should  override  this  method,  so  that  new  objects  in  their  class  will  always  have  a 
sensible  default  view  (device  objects  typically  have  a default  view  of  OPEN  SETTINGS).  The  default 
view  is  used  for  both  the  conditional  Open  cascade  menu  and  double-clicking  on  the  object. 


Related  Methods 

• wpQueryDefauItView 

• wpSetDefauItView 
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#define  INCL_WINWORKPLACE 


PCLASSDET AILS  wpcIsQueryDetails  (M  WPObject  * self) 


The  wpcIsQueryDetails  method  Is  called  to  allow  the  class  object  to  specify  the  default  details  view 
items  for  its  instances. 

Parameters 

self  (M_WPObject  *)  - input 

The  pointer  to  the  class  object. 


Returns 

Success  Indicator: 

NULL  Error  occurred. 

Other  Pointer  to  details  Information. 

Related  Methods 

• wpQueryDetailsData 

• wpcisQueryDetailsinfo 
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WPObject  class  method 


#define  INCL_WINWORKPLACE 


ULONG  wpcIsQueryDetallsInfo  (M_ WPObject  * self,  PCLASSFIELDINFO  pCiassFieldlnfo, 

PULONG  pSIze) 


The  wpcIsQueryDetallsInfo  method  is  called  to  allow  the  class  object  to  specify  its  details  to  be  used 
for  its  instances. 

Parameters 

self  (MWPObject  *)  - input 

The  pointer  to  the  class  object. 
pCiassFieldlnfo  (PCLASSFIELDINFO)  - input/output 
A pointer  to  details  information. 
pSIze  (PULONG)  - input/output 

The  total  number  of  bytes  of  details  data.  This  total  includes  the  details  added  by  this  class  and 
ancestor  classes. 

Returns 

The  sum  of  the  number  of  detail  columns  for  the  object.  This  sum  includes  details  added  by  this 
class  and  ancestor  classes. 

Remarks 

All  objects,  which  have  information  to  display  in  details  view,  must  override  this  method. 

The  two  possible  queries  are: 

Query  1:  A request  for  the  CLASSFIELDINFO  linked  list  segment  associated  with  an  object.  This 
information  is  needed  just  prior  to  changing  the  view  of  container  a control  to  details. 

If  ppCIassFieldlnfo  is  NON-NULL,  ’ppCIassFieldlnfo  points  to  the  head  of  a linked  list  of 
CLASSFIELDINFO  structures  to  which  a linked  list  of  CLASSFIELDINFO  structures  describing  the 
details  fields  of  objects  of  this  subclass  should  be  appended.  (’ppCIassFieldlnfo  may  be  NULL  if  no 
subclasses  have  appended  details  data). 

For  example: 

on  input  ’ppCIassFieldlnfo: 

->CLASSFIELDINFO_l_grandparent_ 

-»CLASSFIELDINF0_2_grandparent-» 

CLASSFIELDINFO_l_parent 

on  output  ’ppCIassFieldlnfo: 

■»CLASSFIELDINFO_l_grandparent_ 

->CLASSFIELDINF0_2_grandparent-> 

CLASSFIELDINFO_l_parent 
-»CLASSFIELDINFO_l_sel  f 

The  correct  way  to  handle  this  request  is  to: 
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• Call  the  parent  method.  The  parent  method  returns  the  number  of  columns  the  ancestors  have 
contributed. 

• Walk  the  chain  of  CLASSFIELDINFO  structures  to  the  end  and  append  the  chain  of 
CLASSFIELDINFO  structures  for  the  current  class  (using  the  pNextFieldlnfo  element). 

• If  ’ppCIassFieldlnfo  is  zero  (indicating  no  parent  columns),  assign  'ppCIassFieldlnfo  = beginning 
of  CLASSFIELDINFO  chain  for  this  subclass. 

• Return  the  sum  of  the  details  columns  of  the  parent  and  the  current  subclass. 


Note  the  following  differences  between  the  CLASSFIELDINFO  and  FIELDINFO  structures: 

• The  offFieldData  and  usLenFieldData  fields  are  required  so  that  appropriate  offsets  for  the  data 
may  be  computed.  The  application  is  responsible  for  providing  offFieldData  and  usLenFieldData 
fields. 

• The  u I Reserved  field  should  be  left  NULL. 

• Owner  draw,  comparison,  and  sort  functions  may  be  specified  for  the  field. 


For  example  if  an  object  has  three  fields: 

typedef  struct  _SAMPLE_DETAIL_DATA  { 
CDATE  cdate; 

CTIME  ctime; 

PSZ  psz ; 

} SAMPLE_DETAIL_DATA; 


cl assfi el dinfo[0] .offFieldData  = FIELDOFFSET(SAMPLE, cdate) ; 
cl assf i el di nf o [0] . ul LenFi el dData  = FIELDOFFSET(SAMPLE, ctime) 

FIELDOFFSET(SAMPLE, cdate) ; 


classfieldinfo[l]. offFieldData  = FIELDOFFSET(SAMPLE, ctime) ; 
cl assfi el di nfo [1] .ul LenFieldData  = FIELDOFFSET(SAMPLE.psz)  - 

F IELDOFFSET ( SAMPLE .ctime) ; 


classfieldinfo[2]. offFieldData  = FIELDOFFSET(SAMPLE.psz) ; 
classfieldinfo[2] .ul LenFieldData  = sizeof (SAMPLE)  - 

FIELDOFFSET (SAMPLE , psz) ; 


Note  that  'ppCIassFieldlnfo  must  be  modified  to  point  to  the  beginning  of  the  CLASSFIELDINFO  linked 
list  only  if  'ppCIassFieldlnfo  is  0. 


The  application  must  return  the  sum  of  the  details  columns  of  the  parent  and  itself: 
return(n_cols  + n_parent_cols) ; 

Note  also  that  the  fields  MUST  be  set  up  sequentially.  classfieldinfo[0]  must  point  to  data  at  an  offset 
of  0.  classfieldinfo[n]  must  point  to  data  adjacent  and  directly  following  that  described  by 
classfieldinfo[— 1]. 

Query  2:  The  number  of  bytes  of  details  data  associated  with  an  object.  This  information  is  needed 
prior  to  allocating  memory  for  a container  control  insert  record. 


If  pSize  is  NON-NULL,  the  override  should  adjust  *pSize  by  the  number  of  bytes  which  must  be  added 
to  the  end  of  a MINIRECORDCORE  structure  to  hold  the  details  information  for  objects  of  this  class. 
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Example: 

*pSize  +=  bytes_of_details_data; 

In  the  case  of  the  above  example, 

*pSize  +=  si  zeof  (SAMPLE_DETAIL_DATA) ; 

NOTE:  All  class  field  pointers  returned  should  be  pointers  to  static  data  areas. 

Usage 

This  method  is  generally  only  called  by  the  system. 

How  to  Override 

This  method  should  be  overridden  by  classes  which  introduce  class-specific  details  to  be  displayed 
in  details  view. 

Related  Methods 

• wpQueryDetailsData 

• wpcisQueryDetails 
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WPPalette  class  method 


#define  INCL_WINWORKPLACE 


PSZ  wpcIsQueryEditString  (M_WPPalette  * self) 


The  wpcIsQueryEditString  method  is  called  to  allow  the  class  object  to  specify  the  text  to  be  used  in 
the  edit  pushbutton  of  the  palette  object's  open  view. 


Parameters 

self  (M_WPPalette  *)  - input 

The  pointer  to  the  class  object. 


Returns 

A pointer  to  the  edit  pushbutton  string. 

Usage 

This  method  can  be  called  at  any  time  in  order  to  determine  the  text  of  the  edit  pushbutton. 

How  to  Override 

This  method  should  be  overridden  in  order  to  specify  class-specific  edit  pushbutton  text.  The  parent 
method  is  generally  not  called. 
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WPObject  class  method 


#define  INCL_WINWORKPLACE 


ULONG  wpcIsQueryError  (M_WPOb]ect  * somSelf) 


The  wpcIsQueryError  class  method  queries  the  current  error  code  held  within  a class  object. 

Parameters 

somSelf  (M_WPObject  *)  - input 
The  pointer  to  the  class  object. 


Returns 

The  last  error  that  occurred  when  using  this  class  object. 


Remarks 

When  an  error  occurs  within  a class  method  and  that  method  subsequently  fails,  the  calling 
procedure  can  retrieve  the  error  code  for  that  failed  method  call  by  using  the  wpcIsQueryError 
method.  Note  that  the  error  code  is  always  that  of  the  last  method  that  failed.  A successful  method 
does  not  modify  the  error  code  held  within  a class  object.  This  function  is  analogous  to  the 
WinGetErrorlnfo  and  the  WinGetLastError  function  calls  that  are  used  by  Presentation  Manager 
applications  to  diagnose  the  reason  for  the  previous  failing  call  to  a Presentation  Manager  function 
call. 

The  system  provided  class  methods  will  return  error  codes  as  defined  in  the  header  file  PMERR.H. 
For  example:  the  wpcisQueryObject  method  will  normally  log  an  error  of 
WPERR_OBJECT_NOT_FOUND  if  it  is  unable  to  return  an  object  pointer. 

Usage 

This  method  should  be  called  immediately  after  a class  method  has  failed,  in  order  to  diagnose  why 
the  failure  occurred. 

How  to  Override 

Never  override  this  class  method 

Related  Methods 

• wpcIsSetError 
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#define  INCL_WINWORKPLACE 


WPFolder  * wpcIsQueryFolder  (M_WPObject  * self,  PSZ  pszLocatlon,  BOOL  fLock) 


The  wpcIsQueryFolder  method  is  called  to  get  a pointer  to  a folder  object  that  corresponds  to  a given 
file  system  location. 


Parameters 

self  (M_WPObject  *)  - input 

The  pointer  to  the  class  object. 

pszLocatlon  (PSZ)  - input 
Folder  location. 


This  value  can  be  in  any  of  the  following  formats: 


• Predefined  object  ids  of  system  folders. 


“<WP_NOWHERE>” 

“<WP_DESKTOP>” 

“<WP_OS2SYS>” 

“<WP_TEMPS>” 

“<WP_CONFIG>” 

“<WP_START>” 

“<WP_INFO>” 

“<WP_DRIVES>” 


The  hidden  folder. 

The  Desktop. 

The  Systerh  folder. 

The  Templates  folder. 
The  System  Setup  folder. 
The  Startup  folder. 

The  Information  folder. 
The  Drives  folder. 


• Real  name  specified  as  a fully  qualified  path  name. 

fLock  (BOOL)  - input 
The  lock  object  flag. 

If  this  flag  is  false,  the  newly  created  object  will  be  made  dormant  whenever  the  object  and  the 
folder  containing  the  object  are  closed.  If  this  flag  is  true,  the  new  flag  will  remain  active  until 
the  caller  issues  the  wpUnlockObject  method  on  it. 


Returns 

Success  indicator: 

NULL  Error  occurred. 

Other  Pointer  to  a folder  object. 

Remarks 

To  obtain  a real  name  from  an  object  pointer,  the  wpQueryRealName  method  should  be  called. 

Usage 

This  method  can  be  called  at  any  time  in  order  to  determine  the  object  pointer  for  a folder. 

How  to  Override 

This  method  is  generally  not  overridden. 
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#define  INCL_WINWORKPLACE 


HPOINTER  wpcIsQuerylcon  (M_WPObject  * selO 


The  wpcIsQuerylcon  method  is  called  to  allow  the  class  object  to  specify  the  default  icon  to  be  used 
for  its  instances. 

Parameters 

self  (M  WPObject  *)  - input 

The  pointer  to  the  class  object. 


Returns 

Success  Indicator: 

NULL  Error  occurred. 

Other  Handle  to  an  icon. 

Remarks 

The  class  default  icon  can  be  loaded  on  wpcIsInitData  and  freed  on  wpcIsUnlnitData. 

Usage 

This  method  can  be  called  at  any  time  in  order  to  determine  the  default  icon  for  instances  of  this 
class. 

How  to  Override 

This  method  is  overridden  in  order  to  change  the  default  icon  for  an  instance  of  the  class. 


Related  Methods 

• wpQuerylcon 

• wpQuerylconData 

• wpSetlcon 

• wpSetlconData 

• wpcisQuerylconData 
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wpcIsQuery  Icon  Data  - 
WPObject  class  method 


#define  INCL_WINWORKPLACE 


ULONG  wpcIsQueryiconOata  (MWPObject  * somSelf,  PICONINFO  plconlnfo) 


The  wpcIsQuerylconData  class  method  allows  the  system  to  build  the  class  default  icon  for  a given 
class. 

Parameters 

somSelf  (M_WPObject  *)  - input 
The  pointer  to  a class  object, 
plconlnfo  (PICONINFO)  - input/output 

A handle  to  the  container  control  window.  If  this  parameter  is  NULLHANDLE,  the  size  should  still 
be  returned  correctly. 


Returns 

The  size  of  the  buffer  needed  to  accommodate  the  ICONOINFO  buffer  that  is  returned  by  this 
particular  class  object. 


Remarks 

If  NULLHANDLE  is  passed  for  the  plconlnfo  parameter,  the  caller  is  asking  for  the  size  of  the 
ICONINFO  buffer  needed  for  this  class  usually  for  memory  allocation  purposes.  Otherwise,  the 
plconlnfo  parameter  can  always  be  assumed  to  be  large  enough  to  accommodate  the  ICONINFO  for 
this  class. 

Note  that  the  ICONINFO  structure  allows  you  to  specify  the  default  icon  in  three  different  ways: 

• An  icon  filename 

• A module  name  and  resource  identifier 

• A block  of  binary  data 

However,  only  one  mechanism  need  be  supported  any  given  class.  For  example,  a caller  cannot 
request  one  of  the  three  formats  by  prefilling  the  ICONINFO  structure. 

Usage 

This  method  may  be  called  at  any  time.  Typically,  it  would  not  be  useful  for  another  object  class  to 
make  calls  to  this  method. 


How  to  Override 

Workplace  classes  that  wish  to  have  a unique  class  default  icon  must  override  this  method  and  fill 
out  the  appropriate  fields  within  the  ICONINFO  structure.  In  addition,  the  correct  size  for  the 
ICONINFO  must  always  be  returned. 


Related  Methods 

• wpQuerylcon 

• wpQuerylconData 

• wpSetlcon 

• wpSetlconData 
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wpcIsQuerylnstanceFilter  - 
WPFileSystem  class  method 


#define  INCL_WINWORKPLACE 


PSZ  wpcIsQuerylnstanceFilter  (M_WPFIIeSystem  * self) 


The  wpcIsQuerylnstanceFilter  method  is  called  to  allow  the  class  object  to  specify  the  file  title  filters 
for  instances  of  its  class. 


Parameters 

self  (M_WPFileSystem  *)  - input 
The  pointer  to  the  class  object. 


Returns 

Success  indicator. 

NULL  Error  occurred. 

Other  A pointer  to  a string  containing  file  title  filters.  This  string  can  contain  several  file  title 
filters  separated  by  a comma. 

Example:  “*.TXT,  *.DOC" 

Remarks 

It  is  important  that  the  values  returned  by  this  class  method  are  restricted  to  class  specific  filters. 

For  example,  returning  a filter  of  could  effectively  make  the  system  unstable. 

Usage 

This  method  can  be  called  at  any  time  in  order  to  determine  which  file  title  filters  are  used  to 
determine  instances  of  this  class. 

How  to  Override 

This  method  should  be  overridden  in  order  to  automatically  designate  file  objects  as  instances  of  this 
class.  The  value  returned  by  the  override  method  will  replace  the  current  title  filter  string  which  is 
used  to  designate  instances.  If  the  parent  method  is  called,  it  should  be  called  first. 


Related  Methods 

• wpcisQuerylnstanceType 


9-262  PM  Programming  Reference 


wpcIsQuerylnstanceType  - 
WPFileSystem  class  method 


#define  INCL_WINWORKPLACE 


PSZ  wpcIsQuerylnstanceType  (M_WPFIIeSystem  * self) 


The  wpcIsQuerylnstanceType  method  is  called  to  allow  the  class  object  to  specify  the  file  types  for 
instances  of  its  class. 


Parameters 

self  (M_WPFileSystem  *)  - input 
The  pointer  to  the  class  object. 


Returns 

Success  indicator. 

NULL  Error  occurred. 

Other  A pointer  to  a string  containing  file  types.  This  string  can  contain  several  file  types 
separated  by  a comma. 

Example:  “Plain  Text, C Code” 

Remarks 

It  is  recommended  that  object  classes  should  define  their  own  special  type  strings. 

Usage 

This  method  can  be  called  at  any  time  in  order  to  determine  which  file  types  are  used  to  determine 
instances  of  this  class. 

How  to  Override 

This  method  should  be  overridden  in  order  to  automatically  designate  file  objects  as  instances  of  this 
class.  The  value  returned  by  the  override  method  will  replace  the  current  type  string  which  is  used 
to  designate  instances.  If  the  parent  method  is  called,  it  should  be  called  first. 


Related  Methods 

• wpcIsQuerylnstanceFilter 


Chapter  9.  Workplace  Classes,  Instance  Methods,  and  Class  Methods  9-263 


wpcIsQueryObject  - 
WPObject  class  method 


#define  INCL_WINWORKPLACE 


WPObject  * wpcIsQueryObject  (M_WPObject  * somSelt,  HOBJECT  hObject) 


The  wpcIsQueryObject  class  method  returns  the  object  pointer  for  a given  persistent  object  handle. 

Parameters 

somSelf  (MWPObject  *)  - input 
The  pointer  to  the  class  object. 
hObject  (HOBJECT)  - input 

The  handle  for  a given  object  instance. 


Returns 

The  pointer  to  the  object  that  corresponds  to  the  given  object  handle  or  NULLHANDLE  if  that 
object  no  longer  exists. 


Remarks 

All  workplace  objects  can  be  uniquely  identified  by  a persistent  object  handle  within  a given 
machine.  Once  an  object  handle  is  obtained  for  an  object  (using  the  wpQueryHandle  instance 
method),  the  handle  can  be  used  at  any  subsequent  time  even  if  the  system  was  powered  off  in  the 
meantime,  provided  that  the  object  instance  has  not  been  destroyed.  This  method  is  intended  for  use 
by  objects  that  wish  to  communicate  with  other  objects  using  method  calls.  At  any  point  in  time,  an 
object  can  reestablish  contact  with  another  object  by  using  this  method.  For  example,  a WPShadow 
object  will  use  this  method  to  get  the  object  pointer  to  the  object  it  is  currently  shadowing  when  it  is 
made  awake.  Note  that  the  returned  object  is  locked,  so  that  the  called  object  can  access  the 
returned  pointer  without  the  risk  of  the  object  being  made  dormant.  When  the  object  pointer  is  no 
longer  needed,  the  wpUnlockObject  method  should  be  invoked  to  permit  the  system  to  make  that 
object  dormant  when  all  other  locks  on  it  have  been  released. 

Usage 

This  class  method  is  callable  at  any  time. 


How  to  Override 

This  class  method  should  not  be  overridden. 

Related  Methods 

• wpQueryHandle 
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wpcIsQueryOpenFolders  - 
WPFolder  class  method 


#define  INCL_WINWORKPLACE 


WPFolder  * wpcIsQueryOpenFolders  (M_WPFolder  * self,  WPFolder  * Folder, 

ULONG  ulOptlon,  BOOL  fLock) 


The  wpcIsQueryOpenFolders  method  is  called  to  allow  the  specified  class  to  enumerate  all  open 
folders. 

Parameters 

self  (M_WPFolder  *)  - input 

The  pointer  to  the  class  object. 

Folder  (WPFolder  *)  - input 

The  pointer  to  a folder  object. 

This  field  is  ignored  unless  QC_NEXT  is  specified  in  ulOption 

ulOptlon  (ULONG)  - input 

A flag  indicating  the  folder  to  query: 

QC_FIRST  Return  the  first  open  folder 

QCJ.AST  Return  the  last  open  folder 

QC_NEXT  Return  the  next  open  folder  after  Folder. 

fLock  (BOOL)  - input 
The  lock  object  flag. 

If  this  flag  is  false,  the  newly  created  object  will  be  made  dormant  whenever  the  object  and  the 
folder  containing  the  object  are  closed.  If  this  flag  is  true,  the  new  flag  will  remain  active  until 
the  caller  issues  the  wpUnlockObject  method  on  it. 

Returns 

Success  indicator. 

NULL  Error  occurred  or  QC_NEXT  was  requested  on  last  folder. 

Other  A pointer  to  the  specified  folder  object. 

Usage 

This  method  can  be  called  at  any  time  in  order  to  determine  the  open  folders. 

How  to  Override 

This  method  is  generally  not  overridden. 
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wpcIsQuerySettingsPageSize 
WPObject  class  method 


#define  INCL_WINWORKPLACE 


BOOL  wpcIsQuerySettingsPageSize  (M_WPOb|ect  * somSelf,  PSIZEL  pSIzI) 


The  wpcIsQuerySettingsPageSize  class  method  returns  the  default  size  of  a settings  page  in  dialog 
units  for  instances  of  this  object  class. 


Parameters 

somSelf  (M_WPObject  *)  - input 
The  pointer  to  the  class  object. 
pSIzI  (PSIZEL)  - input/output 

A pointer  to  the  size  structure  containing  the  cx  and  cy  dimensions  of  the  default  settings  page 
for  this  class. 

Returns 

TRUE  The  method  class  call  was  successful. 

FALSE  The  method  class  call  was  unsuccessful. 

Remarks 

An  object  class  that  has  abnormally  shaped  settings  pages  (for  example  the  pages  may  be  very 
wide)  can  use  this  method  to  ensure  that  when  a settings  notebook  is  initially  displayed  for  an 
instance  of  the  object  class,  that  settings  notebook  will  be  of  a suitable  size  to  view  the  whole 
settings  page  without  clipping  it.  The  size  specified  by  this  method  is  only  used  the  very  first  time 
that  a settings  notebook  is  displayed,  thereafter  the  settings  notebook  size  and  position  will  be  saved 
by  the  system  on  a per  object  basis. 

Usage 

This  function  is  callable,  but  unlikely  to  be  useful. 


How  to  Override 

Object  classes  with  unusual  size  requirements  for  their  settings  pages  must  override  this  class 
method  and  change  the  cx  and  cy  values  as  necessary  to  accommodate  their  settings  page  sizes. 


Related  Methods 

• wpOpen 
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wpcIsQueryStyle  - 
WPObject  class  method 


#define  INCL_WINWORKPLACE 


ULONG  wpcIsQueryStyle  (M_WPObject  * self) 


The  wpcIsQueryStyle  method  is  called  to  allow  the  class  object  to  specify  the  default  object  class 
style  for  its  instances. 

Parameters 

self  (M_WPObject  *)  - input 

The  pointer  to  the  class  object. 


Returns 

Class  style  for  this  object: 

CLSSTYLE_NEVERMOVE 

CLSSTYLENEVERSHADOW 

CLSSTYLE_NEVERCOPY 

CLSSTYLENEVERTEMPLATE 

CLSSTYLENEVERDELETE 

CLSSTYLENEVERPRINT 

CLSSTYLENEVERDRAG 

CLSSTYLENEVERVISIBLE 

CLSSTYLENEVERRENAME 


Do  not  allow  move  of  this  object. 

Do  not  allow  create  shadow  of  this  object. 
Do  not  allow  copy  of  this  object. 

Do  not  allow  create  template  for  this  object. 
Do  not  allow  delete  of  this  object. 

Do  not  allow  print  of  this  object. 

Do  not  allow  drag  of  this  object. 

Make  instances  always  invisible. 

Do  not  allow  the  renaming  of  this  object. 


Remarks 

When  an  instance  is  initially  created,  it  has  the  same  object  style  (OBJSTYLE_xxx)  flags  as  its  class 
style  (CLSSTYLE_xxx) . 


Usage 

This  method  can  be  called  at  any  time  in  order  to  determine  the  default  style  for  instances  of  this 
class. 

How  to  Override 

This  method  should  be  overridden  in  order  to  modify  the  default  object  style  for  instances  of  this 
class. 

Related  Methods 

• wpQueryStyle 

• wpSetStyle 
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wpcIsQueryTitle  - 
WPObject  class  method 


#define  INCL_WINWORKPLACE 


PSZ  wpcIsQueryTitle  (M_WPOb|ect  * self) 


The  wpcIsQueryTitle  method  is  called  to  allow  the  class  object  to  specify  the  default  title  for  its 
instances. 


Parameters 

self  (M_WPObject  *)  - input 

The  pointer  to  the  class  object. 


Returns 

Pointer  to  default  title  for  objects  of  this  class. 


Remarks 

The  title  is  used  as  the  default  for  new  instances.  In  addition,  the  title  is  used  to  describe  the  class  in 
facilities  such  as  Find,  Include,  Details,  and  Sort.  The  title  can  be  loaded  on  wpcIsInitData  and  freed 
on  wpcIsUnlnitData. 

Usage 

This  method  can  be  called  at  any  time  in  order  to  determine  the  default  title  for  instances  of  this 
class. 

How  to  Override 

All  classes  should  override  this  method,  so  that  new  objects  and  their  classes  always  have  a 
sensible  default  title. 

Related  Methods 

• wpQueryTitle 

• wpSetTitle 
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wpcIsSetError  - 
WPObject  class  method 


#define  INCL_WINWORKPLACE 


BOOL  wpcIsSetError  (M_WPObject  * somSelf,  ULONG  ulErrorld) 


The  wpcIsSetError  class  method  sets  the  current  error  code  within  a class  object. 

Parameters 

somSelf  (M_WPObject  *)  - input 
The  pointer  to  the  class  object. 
ulErrorld  (ULONG)  - input 
The  error  code. 


Returns 

TRUE  The  error  was  successful ly  stored. 

FALSE  The  error  was  not  successfully  stored. 

Remarks 

This  method  can  be  used  when  writing  class  methods  for  workplace  objects  that  return  boolean 
values.  When  a given  class  method  fails,  the  class  method  can  log  its  error  code  in  the  class  object 
so  that  the  caller  can  later  retrieve  it  using  the  wpcIsQueryError  class  method.  The  function  is 
analogous  to  the  WinSetErrorlnfo  function  call  that  is  used  by  Presentation  Manager  functions  to  log 
their  error  return  codes. 

Usage 

It  is  recommended  that  this  method  should  only  be  called  by  all  class  methods  when  they  do  not 
execute  successfully,  and  nowhere  else. 


How  to  Override 

Never  override  this  class  method 

Related  Methods 

• wpcIsQueryError 
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wpcIsUnlnitData  - 
WPObject  class  method 


#define  INCL_WINWORKPLACE 


VOID  wpcIsUnlnitData  (M_WPObject  * self) 


The  wpcIsUnlnitData  method  is  called  to  allow  the  class  object  to  free  allocated  resources. 

Parameters 

self  (M_WPObject  *)  - input 

The  pointer  to  the  class  object. 


Returns 

The  return  value  is  VOID. 

Usage 

This  method  is  generally  only  called  by  the  system  when  the  class  object  is  made  dormant.  The 
class  object  is  made  dormant  when  the  last  instance  of  this  class  is  made  dormant. 

How  to  Override 

Any  class  that  overrides  the  wpcisInitData  method  to  allocate  resources  for  its  metaclass  instance 
variables  should  override  this  method  to  deallocate  those  resources.  It  is  essential  to  pass  this 
method  onto  the  parent  class  object  after  performing  override  processing. 

Related  Methods 

• wpcisInitData 
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A 

accelerator.  A single  key  stroke  that  invokes  an 
application-defined  function. 

accelerator  table.  Used  to  define  which  key  strokes  are 
treated  as  accelerators  and  the  commands  they  are 
translated  into. 

access  permission.  All  access  rights  that  a user  has 
regarding  an  object. 

action.  One  of  a set  of  defined  tasks  that  a computer 
performs.  Users  request  the  application  to  perform  an 
action  in  several  ways,  such  as  typing  a command, 
pressing  a function  key,  or  selecting  the  action  name 
from  an  action  bar  or  menu. 

action  bar.  The  area  at  the  top  of  a window  that  contains 
the  choices  currently  available  in  the  application 
program. 

action  point.  The  current  position  on  the  screen  at 
which  the  pointer  is  pointing.  (Contrast  with  hotspot  and 
input  focus.) 

active  program.  A program  currently  running  on  the 
computer.  See  also  interactive  program,  noninteractive 
program,  and  foreground  program. 

active  window.  The  window  with  which  the  user  is 
currently  interacting. 

address  space.  (1)  The  range  of  addresses  available  to 
a program.  (2)  The  area  of  virtual  storage  available  for  a 
particular  job. 

alphanumeric  video  output.  Output  to  the  logical  video 
buffer  when  the  video  adapter  is  in  text  mode  and  the 
logical  video  buffer  is  addressed  by  an  application  as  a 
rectangular  array  of  character  cells. 

anchor  block.  An  area  of  Presentation  Manager-internal 
resources  allocated  to  a process  or  thread  that  calls 
Winlnitialize. 

anchorpoint.  A point  in  a window  used  by  a program 
designer  or  by  a window  manager  to  position  a 
subsequently  appearing  window. 

ANSI.  American  National  Standards  Institute. 

APA.  All  points  addressable. 

API.  Application  programming  interface.  The 
formally-defined  programming  language  that  is  between 
an  IBM  application  program  and  the  user  of  the  program. 
See  also  GPI. 

area.  In  computer  graphics,  a filled  shape  such  as  a 
solid  rectangle. 

ASCII.  American  National  Standard  Code  for 
Information  Interchange.  A coded  character  set 


consisting  of  7-bit  coded  characters  (8  bits  including 
parity  check),  used  for  information  interchange  among 
data  processing  systems,  data  communications  systems, 
and  associated  equipment. 

ASCIIZ.  A string  of  ASCII  characters  that  is  terminated 
with  a byte  containing  the  value  0. 

aspect  ratio.  In  computer  graphics,  the  width-to-height 
ratio  of  an  area,  symbol,  or  shape. 

asynchronous.  (1)  Without  regular  time  relationship.  (2) 
Unexpected  or  unpredictable  with  respect  to  the 
execution  of  a program's  instructions.  See  also 
synchronous. 

atom.  A constant  that  represents  a string.  Once  a string 
has  been  defined  as  an  atom,  the  atom  can  be  used  in 
place  of  the  string  to  save  space.  Strings  are  associated 
with  their  respective  atoms  in  an  atom  table.  See  also 
integer  atom. 

atom  table.  Used  to  relate  atoms  with  the  strings  that 
they  represent.  Also  in  the  table  is  the  mechanism  by 
which  the  presence  of  a string  can  be  checked. 

attributes.  Characteristics  or  properties  that  can  be 
controlled,  usually  to  obtain  a required  appearance;  for 
example,  the  color  of  a line.  See  also  graphics  attributes 
and  segment  attributes. 

AVIO.  Advanced  Video  Input/Output. 

B 

background  color.  The  color  in  which  the  background  of 
a graphic  primitive  is  drawn. 

background  mix.  An  attribute  that  determines  how  the 
background  of  a graphic  primitive  is  combined  with  the 
existing  color  of  the  graphics  presentation  space. 
Contrast  with  mix. 

background  program.  In  multiprogramming,  a program 
that  executes  with  a low  priority.  Contrast  with 
foreground  program. 

Bezier  curves.  A mathematical  technique  of  specifying 
smooth  continuous  lines  and  surfaces,  which  require  a 
starting  point  and  a finishing  point  with  several 
intermediate  points  that  influence  or  control  the  path  of 
the  linking  curve.  Named  after  Dr.  P.  BGzier. 

bitmap.  A representation  in  memory  of  the  data 
displayed  on  an  APA  device,  usually  the  screen. 

block.  (1)  A string  of  data  elements  recorded  or 
transmitted  as  a unit.  The  elements  may  be  characters, 
words,  or  logical  records.  (2)  To  combine  two  or  more 
data  elements  in  one  block. 

border.  A visual  indication  (for  example,  a separator 
line  or  a background  color)  of  the  boundaries  of  a 
window. 


Glossary  X-1 


breakpoint.  (1)  An  instruction  in  a program  for  halting 
execution.  Breakpoints  are  usually  established  at 
positions  in  a program  where  halts,  caused  by  external 
intervention,  are  convenient  for  restarting.  (2)  A place  in 
a program,  specified  by  a command  or  a condition, 
where  the  system  halts  execution  and  gives  control  to 
the  workstation  user  or  to  a specified  program. 

bucket.  One  or  more  fields  in  which  the  result  of  an 
operation  is  kept. 

buffer.  (1)  A portion  of  storage  used  to  hold  input  or 
output  data  temporarily.  (2)  To  allocate  and  schedule  the 
use  of  buffers. 

button.  A mechanism  on  a pointing  device,  such  as  a 
mouse,  used  to  request  or  initiate  an  action.  Contrast 
with  pushbutton  and  radio  button. 

c 

cache.  A high-speed  buffer  storage  that  contains 
frequently  accessed  instructions  and  data;  it  is  used  to 
reduce  access  time. 

cached  micro  presentation  space.  A presentation  space 
from  a Presentation  Manager-owned  store  of  micro 
presentation  spaces.  It  can  be  used  for  drawing  to  a 
window  only,  and  must  be  returned  to  the  store  when  the 
task  is  complete. 

call.  (1)  The  action  of  bringing  a computer  program,  a 
routine,  or  a subroutine  into  effect,  usually  by  specifying 
the  entry  conditions  and  jumping  to  an  entry  point.  (2)  T o 
transfer  control  to  a procedure,  program,  routine,  or 
subroutine. 

calling  order.  A sequence  of  instructions  together  with 
any  associated  data  necessary  to  perform  a call.  Also 
known  as  calling  sequence. 

cancel.  An  action  that  removes  the  current  window  or 
menu  without  processing  it,  and  returns  the  previous 
window. 

CASE  statement,  in  C,  provides  the  body  of  a window 
procedure.  There  is  one  CASE  statement  for  each 
message  type  written  to  take  specific  actions. 

cell.  See  character  cell. 

CGA.  Color  graphics  adapter. 

chained  list.  A list  in  which  the  data  elements  may  be 
dispersed  but  in  which  each  data  element  contains 
information  for  locating  the  next.  Synonym  for  linked  list. 

character.  A letter,  digit,  or  other  symbol. 

character  box.  In  computer  graphics,  the  boundary  that 
defines,  in  world  coordinates,  the  horizontal  and  vertical 
space  occupied  by  a single  character  from  a character 
set.  See  also  character  mode.  Contrast  with  character 
cell. 

character  cell.  The  physical,  rectangular  space  in  which 
any  single  character  is  displayed  on  a screen  or  printer 
device.  Position  is  addressed  by  row  and  column 
coordinates.  Contrast  with  character  box. 


character  code.  The  means  of  addressing  a character  in 
a character  set,  sometimes  called  code  point. 

character  mode.  The  character  mode,  in  conjunction 
with  the  fonttype,  determines  the  extent  to  which 
graphics  characters  are  affected  by  the  character  box, 
shear,  and  angle  attributes. 

check  box.  A control  window,  shaped  like  a square 
button  on  the  screen,  that  can  be  in  a checked  or 
unchecked  state.  It  is  used  to  select  one  or  more  items 
from  a list.  Contrast  with  radio  button. 

check  mark.  The  symbol  that  is  used  to  indicate  a 
selected  item  on  a pull-down. 

child  process.  A process  that  is  loaded  and  started  by 
another  process.  Contrast  with  parent  process. 

child  window.  A window  that  is  positioned  relative  to 
another  window  (either  a main  window  or  another  child 
window).  Contrast  with  parent  window. 

choice.  An  option  that  can  be  selected.  The  choice  can 
be  presented  as  text,  as  a symbol  (number  or  letter),  or 
as  an  icon  (a  pictorial  symbol). 

class.  See  window  class. 

class  style.  The  set  of  properties  that  apply  to  every 
window  in  a window  class. 

client  area.  The  area  in  the  center  of  a window  that 
contains  the  main  information  of  the  window. 

clipboard.  An  area  of  main  storage  that  can  hold  data 
being  passed  from  one  PM  application  to  another. 
Various  data  formats  can  be  stored. 

clipping.  In  computer  graphics,  removing  those  parts  of 
a display  image  that  lie  outside  a given  boundary. 

clip  limits.  The  area  of  the  paper  that  can  be  reached  by 
a printer  or  plotter. 

clipping  path.  A clipping  boundary  in  world-coordinate 
space. 

CLOCKS.  Character-device  name  reserved  for  the 
system  clock. 

code  page.  An  assignment  of  graphic  characters  and 
control-function  meanings  to  all  code  points. 

code  point.  Synonym  for  character  code. 

code  segment.  An  executable  section  of  programming 
code  within  a load  module. 

color  dithering.  See  dithering. 

command.  The  name  and  parameters  associated  with 
an  action  that  a program  can  perform. 

command  area.  An  area  composed  of  a command  field 
prompt  and  a command  entry  field. 

command  entry  field.  An  entry  field  in  which  users  type 
commands. 


X-2  PM  Programming  Reference 


command  line.  On  a display  screen,  a display  line 
usually  at  the  bottom  of  the  screen,  in  which  only 
commands  can  be  entered. 

command  prompt.  A field  prompt  showing  the  location 
of  the  command  entry  field  in  a panel. 

Common  Programming  Interface  (CPI).  A consistent  set 
of  specifications  for  languages,  commands,  and  calls  to 
enable  applications  to  be  developed  across  all  SAA 
environments.  See  also  Systems  Application 
Architecture. 

Common  User  Access  (CUA).  A set  of  rules  that  define 
the  way  information  is  presented  on  the  screen,  and  the 
techniques  for  the  user  to  interact  with  the  information. 

compile.  To  translate  a program  written  in  a 
higher-level  programming  language  into  a machine 
language  program. 

COM1,  COM2,  COM3.  Character-device  names  reserved 
for  serial  ports  1 through  3. 

CON.  Character-device  name  reserved  for  the  console 
keyboard  and  screen. 

contiguous.  Touching  or  joining  at  a common  edge  or 
boundary,  for  example,  an  unbroken  consecutive  series 
of  storage  locations. 

control.  The  means  by  which  an  operator  gives  input  to 
an  application.  A choice  corresponds  to  a control. 

Control  Panel.  In  PM,  a program  used  to  set  up  user 
preferences  that  act  globally  across  the  system. 

Control  Program.  The  basic  function  of  OS/2,  including 
DOS  emulation  and  the  support  for  keyboard,  mouse, 
and  video  input/output. 

control  window.  A class  of  window  used  to  handle  a 
specific  kind  of  user  interaction.  Radio  buttons  and 
check  boxes  are  examples. 

correlation.  The  action  of  determining  which  element  or 
object  within  a picture  is  at  a given  position  on  the 
display.  This  follows  a pick  operation. 

CPI.  Common  Programming  Interface. 

critical  extended  attribute.  An  extended  attribute  that  is 
necessary  for  the  correct  operation  of  the  system  or  a 
particular  application. 

CUA.  Common  User  Access. 

current  position.  The  point  from  which  the  next  primitive 
will  be  drawn. 

cursor.  A symbol  displayed  on  the  screen  and 
associated  with  an  input  device.  The  cursor  indicates 
where  input  from  the  device  will  be  placed.  Types  of 
cursors  include  text  cursors,  graphics  cursors,  and 
selection  cursors.  Contrast  with  pointer  and  input  focus. 


D 

data  structure.  (ISO)  The  syntactic  structure  of  symbolic 
expressions  and  their  storage-allocation  characteristics. 

DBCS.  See  double-byte  character  set. 

deadlock.  (1)  Unresolved  contention  for  the  use  of  a 
resource.  (2)  An  error  condition  in  which  processing 
cannot  continue  because  each  of  two  elements  of  the 
process  is  waiting  for  an  action  by,  or  a response  from, 
the  other.  (3)  An  impasse  that  occurs  when  multiple 
processes  are  waiting  for  the  availability  of  a resource 
that  will  not  become  available  because  it  is  being  held  by 
another  process  that  is  in  a similar  wait  state. 

debug.  To  detect,  diagnose,  and  eliminate  errors  in 
programs. 

decipoint.  In  printing,  one  tenth  of  a point.  There  are  72 
points  in  an  inch. 

default  procedure.  Function  provided  by  the 
Presentation  Interface  that  may  be  used  to  process 
standard  messages  from  dialogs  or  windows. 

default  value.  A value  used  when  no  value  is  explicitly 
specified  by  the  user.  For  example,  in  the  graphics 
programming  interface,  the  default  line-type  is  ’solid’. 

descendant.  A process  or  session  that  is  loaded  and 
started  by  a parent  process  or  parent  session. 

Desktop  Manager.  In  PM,  a window  that  displays  a list 
of  groups  of  programs,  each  of  which  can  be  started  or 
stopped. 

desktop  window.  The  window,  corresponding  to  the 
physical  device,  against  which  all  other  types  of  windows 
are  established. 

device  context.  A logical  description  of  a data 
destination  such  as  memory,  metafile,  display,  printer,  or 
plotter.  See  also  direct  device  context,  information 
device  context,  memory  device  context,  metafile  device 
context,  queued  device  context,  and  screen  device 
context. 

device  driver.  A file  that  contains  the  code  needed  to 
attach  and  use  a device  such  as  a display,  printer,  or 
plotter. 

device  space.  Coordinate  space  in  which  graphics  are 
assembled  after  all  GPI  transformations  have  been 
applied.  Device  space  is  defined  in  device-specific  units. 

dialog.  The  interchange  of  information  between  a 
computer  and  its  user  through  a sequence  of  requests  by 
the  user  and  the  presentation  of  responses  by  the 
computer. 

dialog  box.  A type  of  window  that  contains  one  or  more 
controls  for  the  formatted  display  and  entry  of  data.  Also 
known  as  a pop-up  window.  A modal  dialog  box  is  used 
to  implement  a pop-up  window. 

Dialog  Box  Editor.  A WYSIWYG  editor  that  creates 
dialog  boxes  for  communicating  with  the  application 
user. 
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dialog  item.  A component  (for  example,  a menu  or  a 
button)  of  a dialog  box.  Dialog  items  are  also  used  when 
creating  dialog  templates. 

dialog  tag  language.  A markup  language  used  by  the 
DTL  compiler  to  create  dialog  objects. 

dialog  template.  The  definition  of  a dialog  box,  which 
contains  details  of  its  position,  appearance,  and  window 
ID,  and  the  window  ID  of  each  of  its  child  windows. 

direct  device  context.  A logical  description  of  a data 
destination  that  is  a device  other  than  the  screen  (for 
example,  a printer  or  plotter),  and  where  the  output  is 
not  to  go  through  the  spooler.  Its  purpose  is  to  satisfy 
queries.  See  also  device  context. 

direct  manipulation.  The  action  of  using  the  mouse  to 
move  objects  around  the  screen.  For  example,  moving 
files  and  directories  around  in  the  File  Manager. 

direct  memory  access  (DMA).  The  transfer  of  data 
between  main  storage  and  input/output  devices  without 
intervention  by  the  processor. 

directory.  A type  of  file  containing  the  names  and 
controlling  information  for  other  files  or  other 
directories. 

display  point.  Synonym  for  pel. 

dithering.  The  process  used  in  color  displays  whereby 
every  other  pel  is  set  to  one  color,  and  the  intermediate 
pels  are  set  to  another.  Together  they  produce  the  effect 
of  a third  color  at  normal  viewing  distances.  This 
process  can  only  be  used  on  solid  areas  of  color;  it  does 
not  work  on  narrow  lines,  for  example. 

DMA.  Direct  memory  access. 

double-byte  character  set  (DBCS).  A set  of  characters  in 
which  each  character  is  represented  by  two  bytes. 
Languages  such  as  Japanese,  Chinese,  and  Korean, 
which  contain  more  characters  than  can  be  represented 
by  256  code  points,  require  double-byte  character  sets. 
Since  each  character  requires  two  bytes,  the  entering, 
displaying,  and  printing  of  DBCS  characters  requires 
hardware  and  software  that  can  support  DBCS. 

doubleword.  A contiguous  sequence  of  bits  or 
characters  that  comprises  two  computer  words  and  is 
capable  of  being  addressed  as  a unit. 

dragging.  In  computer  graphics,  moving  an  object  on 
the  display  screen  as  if  it  were  attached  to  the  pointer. 

drawing  chain.  See  segment  chain. 

drop.  To  fix  the  position  of  an  object  that  is  being 
dragged,  by  releasing  the  select  button  of  the  pointing 
device. 

DTL.  See  dialog  tag  language. 

dual-boot  function.  A feature  of  OS/2  that  allows  the 
user  to  start  DOS  from  within  OS/2,  or  OS/2  from  within 
DOS. 

duplex.  Pertaining  to  communication  in  which  data  can 
be  sent  and  received  at  the  same  time.  Synonymous 
with  full  duplex. 


dynamic  linking.  The  process  of  resolving  external 
references  in  a program  module  at  load  time  or  run  time 
rather  than  during  linking. 

dynamic-link  library.  A collection  of  executable 
programming  code  and  data  that  is  bound  to  an 
application  at  load  time  or  run  time,  rather  than  during 
linking.  The  programming  code  and  data  in  a dynamic 
link  library  can  be  shared  by  several  applications 
simultaneously. 

dynamic-link  module.  A module  that  is  linked  at  load 
time  or  run  time. 

dynamic  segments.  Graphics  segments  drawn  in 
exclusive-OR  mix  mode  so  that  they  can  be  moved  from 
one  screen  position  to  another  without  affecting  the  rest 
of  the  displayed  picture. 

dynamic  storage.  (1)  A device  that  stores  data  in  a 
manner  that  permits  the  data  to  move  or  vary  with  time 
such  that  the  specified  data  is  not  always  available  for 
recovery.  (2)  A storage  in  which  the  cells  require 
repetitive  application  of  control  signals  in  order  to  retain 
stored  data.  Such  repetitive  application  of  the  control 
signals  is  called  a refresh  operation.  A dynamic  storage 
may  use  static  addressing  or  sensing  circuits.  (3)  See 
also  static  storage. 

E 

EBCDIC.  Extended  binary-coded  decimal  interchange 
code.  A coded  character  set  consisting  of  8-bit  coded 
characters  (9  bits  including  parity  check),  used  for 
information  interchange  among  data  processing 
systems,  data  communications  systems,  and  associated 
equipment. 

EGA.  Extended  graphics  adapter. 

8.3 file-name  format.  A file-naming  convention  in  which 
file  names  are  limited  to  eight  characters  before  and 
three  characters  after  a single  dot.  Usually  pronounced 
“eight-dot-three. ’’  See  also  non-8.3  file-name  format. 

element.  An  entry  in  a graphics  segment  that  comprises 
one  or  more  graphics  orders  and  that  is  addressed  by 
the  element  pointer. 

entry  field.  An  area  on  the  screen,  usually  highlighted  in 
some  manner,  in  which  users  type  information. 

entry-field  control.  The  means  by  which  the  application 
receives  data  entered  by  the  user  in  an  entry  field. 

When  it  has  the  input  focus,  it  displays  a flashing  pointer 
at  the  position  where  the  next  typed  character  will  go. 

entry  panel.  A defined  panel  type  containing  one  or 
more  entry  fields  and  protected  information  such  as 
headings,  prompts,  and  explanatory  text. 

exception.  An  abnormal  condition  such  as  an  I/O  error 
encountered  in  processing  a data  set  or  a file. 

exclusive  system  semaphore.  A system  semaphore  that 
can  be  modified  only  by  threads  within  the  same 
process. 


X-4  PM  Programming  Reference 


exit.  The  action  that  terminates  the  current  function  and 
returns  the  user  to  a higher  level  function.  Repeated  exit 
requests  return  the  user  to  the  point  from  which  all 
functions  provided  to  the  system  are  accessible. 

Contrast  with  cancel. 

extended  attribute.  An  additional  piece  of  information 
about  a file  object,  such  as  its  data  format  or  category.  It 
consists  of  a name  and  a value.  A file  object  may  have 
more  than  one  extended  attribute  associated  with  it. 

extended-choice  selection.  A mode  that  allows  the  user 
to  select  more  than  one  item  from  a window.  Not  all 
windows  allow  extended  choice  selection.  Contrast  with 
multiple-choice  selection. 

extended  help.  A facility  that  provides  users  with 
information  about  an  entire  application  panel  rather  than 
a particular  item  on  the  panel. 

extent.  Continuous  space  on  a disk  or  diskette  that  is 
occupied  by  or  reserved  for  a particular  data  set,  data 
space,  or  file. 

F 

family-mode  application.  An  application  program  that 
can  run  in  the  OS/2  environment  and  in  the  DOS 
environment.  However,  it  cannot  take  advantage  of 
many  of  the  OS/2-mode  facilities,  such  as  multitasking, 
interprocess  communication,  and  dynamic  linking. 

FAT.  File  allocation  table. 

FEA.  Full  extended  attribute. 

field-level  help.  Information  specific  to  the  field  on 
which  the  cursor  is  positioned.  This  help  function  is 
“contextual”  because  it  provides  information  about  a 
specific  item  as  it  is  currently  used;  the  information  is 
dependent  upon  the  context  within  the  work  session. 

file.  A named  set  of  records  stored  or  processed  as  a 
unit. 

file  allocation  table  (FAT).  In  IBM  personal  computers,  a 
table  used  by  the  operating  system  to  allocate  space  on 
a disk  for  a file,  and  to  locate  and  chain  together  parts  of 
the  file  that  may  be  scattered  on  different  sectors  so  that 
the  file  can  be  used  in  a random  or  sequential  manner. 

file  attribute.  Any  of  the  attributes  that  describe  the 
characteristics  of  a file. 

File  Manager.  In  PM,  a program  that  displays 
directories  and  files,  and  allows  various  actions  on  them. 

file  specification.  The  full  identifier  for  a file,  which 
includes  its  drive  designation,  path,  file  name,  and 
extension. 

file  system  driver  (FSD).  A program  that  manages  file 
I/O  and  controls  the  format  of  information  on  the  storage 
media. 

fillet.  A curve  that  is  tangential  to  the  end  points  of  two 
adjoining  lines.  See  also  polyfillet. 

flag.  (1)  An  indicator  or  parameter  that  shows  the 
setting  of  a switch.  (2)  A character  that  signals  the 
occurrence  of  some  condition,  such  as  the  end  of  a word. 


focus.  See  input  focus. 

font.  A particular  size  and  style  of  typeface  that  contains 
definitions  of  character  sets,  marker  sets,  and  pattern 
sets. 

foreground  program.  The  program  with  which  the  user 
is  currently  interacting.  Also  known  as  interactive 
program.  Contrast  with  background  program. 

frame.  The  part  of  a window  that  can  contain  several 
different  visual  elements  specified  by  the  application,  but 
drawn  and  controlled  by  PM.  The  frame  encloses  the 
client  area. 

frame  styles.  Different  standard  window  layouts 
provided  by  PM. 

FSD.  File  system  driver. 

full  duplex.  Synonym  for  duplex. 

full-screen  application.  An  application  program  that 
occupies  the  whole  screen. 

function.  (1)  In  a programming  language,  a block,  with 
or  without  formal  parameters,  whose  execution  is 
invoked  by  means  of  a call.  (2)  A set  of  related  control 
statements  that  cause  one  or  more  programs  to  be 
performed. 

function  key.  A key  that  causes  a specified  sequence  of 
operations  to  be  performed  when  it  is  pressed,  for 
example,  FI  and  Alt-K. 

function  key  area.  The  area  at  the  bottom  of  a window 
that  contains  function  key  assignments  such  as 
FI  = Help. 

G 

GDT.  Global  Descriptor  Table. 

general  protection  fault.  An  exception  condition  that 
occurs  when  a process  attempts  to  use  storage  or  a 
module  that  has  some  level  of  protection  assigned  to  it, 
such  as  I/O  privilege  level.  See  also  IOPL  code  segment. 

Global  Descriptor  Table  (GDT).  Defines  code  and  data 
segments  available  to  all  tasks  in  an  application. 

global  dynamic-link  module.  A dynamic-link  module  that 
can  be  shared  by  all  processes  in  the  system  that  refer 
to  the  module  name. 

global  file-name  character.  A special  character  used  to 
refer  to  a set  of  file  objects  with  a common  base  name. 
The  asterisk  (*)  and  question  mark  (?)  are  used  as  global 
file-name  characters.  For  example,  '.EXE  can  be  used  to 
refer  to  a set  of  files  with  the  extension  EXE. 

glyph.  A graphic  symbol  whose  appearance  conveys 
information. 

GPI.  Graphics  programming  interface.  The 
formally-defined  programming  language  that  is  between 
an  IBM  graphics  program  and  the  user  of  the  program. 
See  also  API. 
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graphics.  A picture  defined  in  terms  of  graphic 
primitives  and  graphics  attributes. 

graphics  attributes.  Attributes  that  apply  to  graphic 
primitives.  Examples  are  color,  line  type,  and 
shading-pattern  definition.  See  also  segment  attributes. 

graphics  field.  The  clipping  boundary  that  defines  the 
visible  part  of  the  presentation-page  contents. 

graphics  model  space.  The  conceptual  coordinate 
space  in  which  a picture  is  constructed  after  any  model 
transforms  have  been  applied.  Also  known  as  model 
space. 

graphic  primitive.  A single  item  of  drawn  graphics,  such 
as  a line,  arc,  or  graphics  text  string.  See  also  graphics 
segment. 

graphics  segment.  A sequence  of  related  graphic 
primitives  and  graphics  attributes.  See  also  graphic 
primitive. 

graying.  The  indication  that  a choice  on  a pull-down  is 
unavailable. 

group.  A collection  of  logically-connected  controls.  For 
example,  the  buttons  controlling  paper  size  for  a printer. 
See  also  program  group. 

H 

handle.  An  identifier  that  represents  an  object,  such  as 
a device  or  window,  to  the  Presentation  Interface. 

hard  error.  An  error  condition  on  a network  that 
requires  either  that  the  system  be  reconfigured,  or  that 
the  source  of  the  error  be  removed  before  the  system 
can  resume  reliable  operation. 

header.  (1)  System-defined  control  information  that 
precedes  user  data.  (2)  The  portion  of  a message  that 
contains  control  information  for  the  message,  such  as 
one  or  more  destination  fields,  name  of  the  originating 
station,  input  sequence  number,  character  string 
indicating  the  type  of  message,  and  priority  level  for  the 
message. 

help.  A function  that  provides  information  about  a 
specific  field,  an  application  panel,  or  information  about 
the  help  facility. 

help  index.  A facility  that  allows  the  user  to  select  topics 
for  which  help  is  available. 

help  panel.  A panel  with  information  to  assist  users  that 
is  displayed  in  response  to  a help  request  from  the  user. 

help  window.  A Common  User  Access-defined 
secondary  window  that  displays  information  when  the 
user  requests  help. 

heap.  An  area  of  free  storage  available  for  dynamic 
allocation  by  an  application.  Its  size  varies  according  to 
the  storage  requirements  of  the  application. 

hit  testing.  The  means  of  identifying  which  window  is 
associated  with  which  input  device  event. 

hook.  A mechanism  by  which  procedures  are  called 
when  certain  events  occur  in  the  system.  For  example, 


the  filtering  of  mouse  and  keyboard  input  before  it  is 
received  by  an  application  program. 

hook  chain.  A sequence  of  hook  procedures  that  are 
“chained"  together  so  that  each  event  is  passed,  in  turn, 
to  each  procedure  in  the  chain. 

hot  spot.  The  part  of  the  pointer  that  must  touch  an 
object  before  it  can  be  selected.  This  is  usually  the  tip  of 
the  pointer.  Contrast  with  action  point. 

I 

icon.  A pictorial  representation  of  an  item  the  user  can 
select.  Icons  can  represent  items  (such  as  a document 
file)  that  the  user  wants  to  work  on,  and  actions  that  the 
user  wants  to  perform.  In  PM,  icons  are  used  for  data 
objects,  system  actions,  and  minimized  programs. 

icon  area.  In  PM,  the  area  at  the  bottom  of  the  screen 
that  is  normally  used  to  display  the  icons  for  minimized 
programs. 

Icon  Editor.  The  Presentation  Manager-provided  tool  for 
creating  icons. 

image  font.  A set  of  symbols,  each  of  which  is  described 
in  a rectangular  array  of  pels.  Some  of  the  pels  in  the 
array  are  set  to  produce  the  image  of  the  symbol. 
Contrast  with  outline  font. 

information  device  context.  A logical  description  of  a 
data  destination  other  than  the  screen  (for  example,  a 
printer  or  plotter),  but  where  no  output  will  occur.  Its 
purpose  is  to  satisfy  queries.  See  also  device  context. 

information  panel.  A defined  panel  type  characterized 
by  a body  containing  only  protected  information. 

input  focus.  The  area  of  the  screen  that  will  receive 
input  from  an  input  device  (typically  the  keyboard). 

input  router.  An  internal  OS/2  process  that  removes 
messages  from  the  system  queue. 

integer  atom.  A special  kind  of  atom  that  represents  a 
predefined  system  constant  and  carries  no  storage 
overhead.  For  example,  names  of  window  classes 
provided  by  PM  are  expressed  as  integer  atoms. 

interactive  graphics.  Graphics  that  can  be  moved  or 
manipulated  by  a user  at  a terminal. 

interactive  program.  A program  that  is  running  (active) 
and  is  ready  to  receive  (or  is  receiving)  input  from  the 
user.  Compare  with  active  program  and  contrast  with 
noninteractive  program. 

Also  known  as  a foreground  program. 

interchange  file.  Data  that  can  be  sent  from  one 
Presentation  Interface  application  to  another. 

interval  timer.  (1)  A timer  that  provides  program 
interruptions  on  a program-controlled  basis.  (2)  An 
electronic  counter  that  counts  intervals  of  time  under 
program  control. 

lOCtl.  A device-specific  command  that  requests  a 
function  of  a device  driver  through  the  DosDevlOCtl 
function. 


X-6  PM  Programming  Reference 


I/O  operation.  An  input  operation  to,  or  output  operation 
from  a device  attached  to  a computer. 

IOPL.  Input/output  privilege  level. 

IOPL  code  segment.  An  IOPL  executable  section  of 
programming  code  that  enables  an  application  to  directly 
manipulate  hardware  interrupts  and  ports  without 
replacing  the  device  driver.  See  also  privilege  level. 

J 


local  area  network  (LAN).  A data  network  located  on  the 
user’s  premises  in  which  serial  transmission  is  used  for 
direct  data  communication  among  data  stations. 

Local  Descriptor  Table  (LDT).  Defines  code  and  data 
segments  specific  to  a single  task. 

lock.  A serialization  mechanism  by  means  of  which  a - 
resource  is  restricted  for  use  by  the  holder  of  the  lock. 

LPT1,  LPT2,  LPT3.  Character-device  names  reserved  for 
parallel  printers  1 through  3. 


journal.  A special-purpose  file  that  is  used  to  record 
changes  made  in  the  system. 

K 

Kanjl.  A graphic  character  set  used  in  Japanese 
ideographic  alphabets. 

KBD$.  Character-device  name  reserved  for  the 
keyboard. 

kernel.  The  part  of  an  operating  system  that  performs 
basic  functions,  such  as  allocating  hardware  resources. 

kerning.  The  design  of  graphics  characters  so  that  their 
character  boxes  overlap.  Used  to  space  text 
proportionally. 

keys  help.  A facility  that  gives  users  a listing  of  all  the 
key  assignments  for  the  current  application. 

L 

label.  In  a graphics  segment,  an  identifier  of  one  or 
more  elements  that  is  used  when  editing  the  segment. 

language  support  procedure.  Function  provided  by  the 
Presentation  Interface  for  applications  that  do  not,  or 
cannot  (as  in  the  case  of  COBOL  and  FORTRAN 
programs),  provide  their  own  dialog  or  window 
procedures. 

LDT.  Local  Descriptor  Table. 

LIFO  stack.  A data  stack  from  which  data  is  retrieved  in 
last-in,  first-out  order. 

linked  list.  Synonym  for  chained  list. 

list  box.  A control  window  containing  a vertical  list  of 
selectable  descriptions. 

list  panel.  A defined  panel  type  that  displays  a list  of 
items  from  which  users  can  select  one  or  more  choices 
and  then  specify  one  or  more  actions  to  work  on  those 
choices. 

load-on-call.  A function  of  a linkage  editor  that  allows 
selected  segments  of  the  module  to  be  disk  resident 
while  other  segments  are  executing.  Disk  resident 
segments  are  loaded  for  execution  and  given  control 
when  any  entry  point  that  they  contain  is  called. 

load  time.  The  point  in  time  at  which  a program  module 
is  loaded  into  main  storage  for  execution. 


M 

main  window.  The  window  that  is  positioned  relative  to 
the  desktop  window. 

map.  (1)  A set  of  values  having  a defined 
correspondence  with  the  quantities  or  values  of  another 
set.  (2)  To  establish  a set  of  values  having  a defined 
correspondence  with  the  quantities  or  values  of  another 
set. 

marker  box.  In  computer  graphics,  the  boundary  that 
defines,  in  world  coordinates,  the  horizontal  and  vertical 
space  occupied  by  a single  marker  from  a marker  set. 

marker  symbol.  A symbol  centered  on  a point.  Graphs 
and  charts  can  use  marker  symbols  to  indicate  the 
plotted  points. 

maximize.  A window-sizing  action  that  makes  the 
window  the  largest  size  possible. 

media  window.  The  part  of  the  physical  device  (display, 
printer,  or  plotter)  on  which  a picture  is  presented. 

memory  device  context.  A logical  description  of  a data 
destination  that  is  a memory  bit  map.  See  also  device 
context. 

memory  management.  A feature  of  the  operating 
system  for  allocating,  sharing,  and  freeing  main  storage. 

menu.  A type  of  panel  that  consists  of  one  or  more 
selection  fields.  Also  called  a menu  panel. 

message.  (1)  In  PM,  a packet  of  data  used  for 
communication  between  the  Presentation  Interface  and 
windowed  applications.  (2)  In  a user  interface, 
information  not  requested  by  users  but  presented  to 
users  by  the  computer  in  response  to  a user  action  or 
internal  process. 

message  filter.  The  means  of  selecting  which  messages 
from  a specific  window  will  be  handled  by  the 
application. 

message  queue.  A sequenced  collection  of  messages  to 
be  read  by  the  application. 

metafile.  The  generic  name  for  the  definition  of  the 
contents  of  a picture.  Metafiles  are  used  to  allow 
pictures  to  be  used  by  other  applications. 

metafile  device  context.  A logical  description  of  a data 
destination  that  is  a metafile,  which  is  used  for  graphics 
interchange.  See  also  device  context. 
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metalanguage.  A language  used  to  specify  another 
language.  For  example,  data  types  can  be  described 
using  a metalanguage  so  as  to  make  the  descriptions 
independent  of  any  one  computer  language. 

mickey.  A unit  of  measurement  for  physical  mouse 
motion  whose  value  depends  on  the  mouse  device  driver 
currently  loaded. 

micro  presentation  space.  A graphics  presentation 
space  in  which  a restricted  set  of  the  GPI  function  calls  is 
available. 

minimize.  A window-sizing  action  that  makes  the 
window  the  smallest  size  possible.  In  PM,  minimized 
windows  are  represented  by  icons. 

mix.  An  attribute  that  determines  how  the  foreground  of 
a graphic  primitive  is  combined  with  the  existing  color  of 
graphics  output.  Also  known  as  foreground  mix. 

Contrast  with  background  mix. 

mixed  character  string.  A string  containing  a mixture  of 
one-byte  and  Kanji  or  Hangeul  (two-byte)  characters. 

mnemonic.  A method  of  selecting  an  item  on  a 
pull-down  by  means  of  typing  the  highlighted  letter  in  the 
menu  item. 

modal  dialog  box.  The  type  of  control  that  allows  the 
operator  to  perform  input  operations  on  only  the  current 
dialog  box  or  one  of  its  child  windows.  Also  known  as  a 
serial  dialog  box.  Contrast  with  parallel  dialog  box. 

modeless  dialog  box.  The  type  of  control  that  allows  the 
operator  to  perform  input  operations  on  any  of  the 
application’s  windows.  Also  known  as  a parallel  dialog 
box.  Contrast  with  modal  dialog  box. 

model  space.  See  graphics  model  space. 

module  definition  file.  A file  that  describes  the  code 
segments  within  a load  module.  For  example,  it 
indicates  whether  a code  segment  is  loadable  before 
module  execution  begins  (preload),  or  loadable  only 
when  referred  to  at  run  time  (load-on-call). 

mouse.  A hand-held  device  that  is  moved  around  to 
position  the  pointer  on  the  screen. 

MOUSES.  Character-device  name  reserved  for  a mouse. 

multiple-choice  selection.  A mode  that  allows  users  to 
select  any  number  of  choices,  including  none  at  all.  See 
also  check  box.  Contrast  with  extended-choice 
selection. 

multitasking.  The  concurrent  processing  of  applications 
or  parts  of  applications.  A running  application  and  its 
data  are  protected  from  other  concurrently  running 
applications. 

N 

named  pipe.  A named  buffer  that  provides 
client-to-server,  server-to-client,  or  full  duplex 
communication  between  unrelated  processes.  Contrast 
with  unnamed  pipe. 

noncritical  extended  attribute.  An  extended  attribute 
that  is  not  necessary  for  the  function  of  an  application. 


nondestructive  read.  A read  process  that  does  not 
erase  the  data  in  the  source  location. 

non-8.3  file-name  format.  A file-naming  convention  in 
which  path  names  can  consist  of  up  to  255  characters. 
See  also  8.3  file-name  format. 

nonlnteractlve  program.  A program  that  is  running 
(active)  but  is  not  ready  to  receive  input  from  the  user. 
Compare  with  active  program,  and  contrast  with 
interactive  program. 

nonretalned  graphics.  Graphic  primitives  that  are  not 
remembered  by  the  Presentation  Interface  once  they 
have  been  drawn.  Contrast  with  retained  graphics. 

NUL.  Character-device  name  reserved  for  a nonexistent 
(dummy)  device. 

null-terminated  string.  A string  of  (n  + 1)  characters 
where  the  (n  -i-  1)th  character  is  the  ’null'  character 
(X'OO'j,  and  is  used  to  represent  an  n-character  string 
with  implicit  length.  Also  known  as  ’zero-terminated’ 
string  and  ’ASCIIZ’  string. 

o 

object  window.  A window  that  does  not  have  a parent, 
but  which  may  have  child  windows.  An  object  window 
cannot  be  presented  on  a device. 

open.  To  start  working  with  a file,  directory,  or  other 
object. 

outline  font.  A set  of  symbols,  each  of  which  is  created 
as  a series  of  lines  and  curves.  Synonymous  with  vector 
font.  Contrast  with  image  font. 

output  area.  The  area  of  the  output  device  within  which 
the  picture  is  to  be  displayed,  printed,  or  plotted. 

owner  window.  A window  into  which  specific  events  that 
occur  in  another  (owned)  window  are  reported. 

owning  process.  The  process  that  owns  the  resources 
that  may  be  shared  with  other  processes. 

P 

page.  A 4KB  segment  of  contiguous  physical  memory. 

page  viewport.  A boundary  in  device  coordinates  that 
defines  the  area  of  the  output  device  in  which  graphics 
are  to  be  displayed.  The  presentation-page  contents  are 
transformed  automatically  to  the  page  viewport  in  device 
space. 

paint.  The  action  of  drawing  or  redrawing  the  contents 
of  a window. 

panel.  A particular  arrangement  of  information  grouped 
together  for  presentation  to  the  user  in  a window. 

panel  area.  An  area  within  a panel  that  contains  related 
information.  The  three  major  Common  User 
Access-defined  panel  areas  are  the  action  bar,  the 
function  key  area,  and  the  panel  body. 
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panel  body.  The  portion  of  a panel  not  occupied  by  the 
action  bar,  function  key  area,  title  or  scroll  bars.  The 
panel  body  may  contain  protected  information,  selection 
fields,  and  entry  fields.  The  layout  and  content  of  the 
panel  body  determine  the  panel  type. 

panel  body  area.  The  part  of  a window  not  occupied  by 
the  action  bar  or  function  key  area.  The  panel  body  area 
may  contain  information,  selection  fields,  and  entry 
fields.  Also  known  as  client  area. 

panel  body  area  separator.  A line  or  color  boundary 
that  provides  users  with  a visual  distinction  between  two 
adjacent  areas  of  a panel. 

panel  definition.  A description  of  the  contents  and 
characteristics  of  a panel.  A panel  definition  is  the 
application  developer’s  mechanism  for  predefining  the 
format  to  be  presented  to  users  in  a window. 

panel  ID.  A panel  element  located  in  the  upper  left-hand 
corner  of  a panel  body  that  identifies  that  particular 
panel  within  the  application. 

panel  title.  A panel  element  that  identifies  the 
information  in  the  panel. 

paper  size.  The  size  of  paper,  defined  in  either  standard 
U.S.  or  European  names  (for  example,  A,  B,  A4),  and 
measured  in  inches  or  millimeters  respectively. 

parallel  dialog  box.  See  modeless  dialog  box. 

parent  process.  A process  that  loads  and  starts  other 
processes.  Contrast  with  child  process. 

parent  window.  The  window  relative  to  which  one  or 
more  child  windows  are  positioned.  Contrast  with  child 
window. 

partition.  (1)  A fixed-size  division  of  storage.  (2)  On  an 
IBM  personal  computer  fixed  disk,  one  of  four  possible 
storage  areas  of  variable  size;  one  may  be  accessed  by 
DOS,  an  d each  of  the  others  may  be  assigned  to  another 
operating  system. 

path.  The  part  of  a file  specification  that  lists  a series  of 
directory  names.  Each  directory  name  is  separated  by 
the  backslash  character.  In  the  file  specification 
C:\MYFILES\MISC\GLOSSARY.SCR,  the  path  consists  of 
MYFILES\MISC\. 

pel.  The  smallest  area  of  a display  screen  capable  of 
being  addressed  and  switched  between  visible  and 
invisible  states.  Synonym  for  display  point,  pixel,  and 
picture  element. 

pick.  To  select  part  of  a displayed  object  using  the 
pointer. 

picture  chain.  See  segment  chain. 
picture  element.  Synonym  for  pel. 

PID.  Process  identification. 

pipe.  A named  or  unnamed  buffer  used  to  pass  data 
between  processes.  A process  reads  from  or  writes  to  a 
pipe  as  if  the  pipe  were  a standard-input  or 


standard-output  file.  See  also  named  pipe  and  unnamed 
pipe. 

pixel.  Synonym  for  pel. 

plotter.  An  output  device  that  uses  pens  to  draw  its 
output  on  paper  or  on  transparency  foils. 

PM.  Presentation  Manager. 

pointer.  (1)  The  symbol  displayed  on  the  screen  that  is 
moved  by  a pointing  device,  such  as  a mouse.  The 
pointer  is  used  to  point  at  items  that  users  can  select. 
Contrast  with  cursor.  (2)  A data  element  that  indicates 
the  location  of  another  data  element. 

POINTERS.  Character-device  name  reserved  for  a 
pointer  device  (mouse  screen  support). 

pointing  device.  A device  (such  as  a mouse)  used  to 
move  a pointer  on  the  screen. 

pointings.  Pairs  of  x-y  coordinates  produced  by  an 
operator  defining  positions  on  a screen  with  a pointing 
device,  such  as  a mouse. 

polyfillet.  A curve  based  on  a sequence  of  lines.  It  is 
tangential  to  the  end  points  of  the  first  and  last  lines,  and 
tangential  also  to  the  midpoints  of  all  other  lines.  See 
also  fillet. 

polyline.  A sequence  of  adjoining  lines. 

pop.  To  retrieve  an  item  from  a last-in-first-out  stack  of 
items.  Contrast  with  push. 

pop-up  window.  A window  that  appears  on  top  of 
another  window  in  a dialog.  Each  pop-up  window  must 
be  completed  before  returning  to  the  underlying  window. 

Presentation  Manager  (PM).  The  visual  component  of 
OS/2  that  presents,  in  windows,  a graphics-based 
interface  to  applications  and  files  installed  and  running 
in  OS/2. 

presentation  page.  The  coordinate  space  in  which  a 
picture  is  assembled  for  display. 

presentation  space  (PS).  Contains  the 
device-independent  definition  of  a picture. 

primary  window.  The  window  in  which  the  main  dialog 
between  the  user  and  the  application  takes  place.  In  a 
multiprogramming  environment,  each  application  starts 
in  its  own  primary  window.  The  primary  window  remains 
for  the  duration  of  the  application,  although  the  panel 
displayed  will  change  as  the  user’s  dialog  moves 
forward.  See  also  secondary  window. 

primitive.  See  graphic  primitive. 

primitive  attribute.  A specifiable  characteristic  of  a 
graphic  primitive.  See  graphics  attributes. 

print  job.  The  result  of  sending  a document  or  picture  to 
be  printed. 

Print  Manager.  In  PM,  the  part  of  the  spooler  that 
manages  the  spooling  process.  It  also  allows  users  to 
view  print  queues  and  to  manipulate  print  jobs. 
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privilege  level.  A protection  level  imposed  by  the 
hardware  architecture  of  the  IBM  personal  computer. 
There  are  four  privilege  levels  (number  0 through  3). 
Only  certain  types  of  programs  are  allowed  to  execute  at 
each  privilege  level.  See  also  IOPL  code  segment. 

procedure  call.  In  programming  languages,  a language 
construct  for  invoking  execution  of  a procedure. 

process.  An  instance  of  an  executing  application  and 
the  resources  it  is  using. 

program  details.  Information  about  a program  that  is 
specified  in  the  Program  Manager  window  and  is  used 
when  the  program  is  started. 

program  group.  In  PM,  several  programs  that  can  be 
acted  upon  as  a single  entity. 

program  name.  The  full  file  specification  of  a program. 
Contrast  with  program  title. 

program  title.  The  name  of  a program  as  it  is  listed  in 
the  Program  Manager  window.  Contrast  with  program 
name. 

prompt.  A displayed  symbol  or  message  that  requests 
input  from  the  user  or  gives  operational  information. 

The  user  must  respond  to  the  prompt  in  order  to 
proceed. 

protocol.  A set  of  semantic  and  syntactic  rules  that 
determines  the  behavior  o functional  units  in  achieving 
communication. 

pseudocode.  An  artificial  language  used  to  describe 
computer  program  algorithms  without  using  the  syntax  of 
any  particular  programming  language. 

pull-down.  An  action  bar  extension  that  displays  a list  of 
choices  available  for  a selected  action  bar  choice.  After 
users  select  an  action  bar  choice,  the  pull-down  appears 
with  the  list  of  choices.  Additional  pop-up  windows  may 
appear  from  pull-down  choices  to  further  extend  the 
actions  available  to  users. 

push.  To  add  an  item  to  a last-in-first-out  stack  of  items. 
Contrast  with  pop. 

pushbutton.  A control  window,  shaped  like  a 
round-cornered  rectangle  and  containing  text,  that 
invokes  an  immediate  action,  such  as  ’enter’  or  ’cancel’. 

Q 

queue.  A linked  list  of  elements  waiting  to  be 
processed.  For  example,  a queue  may  be  a list  of  print 
jobs  waiting  to  be  printed. 

queued  device  context.  A logical  description  of  a data 
destination  (for  example,  a printer  or  plotter)  where  the 
output  is  to  go  through  the  spooler.  See  also  device 
context. 


R 

radio  button.  A control  window,  shaped  like  a round 
button  on  the  screen,  that  can  be  in  a checked  or 
unchecked  state.  It  is  used  to  select  a single  item  from 
list.  Contrast  with  check  box. 

HAS.  Reliability,  availability,  and  serviceability. 

raster.  (1)  In  computer  graphics,  a predetermined 
pattern  of  lines  that  provides  uniform  coverage  of  a 
display  space.  (2)  The  coordinate  grid  that  divides  the 
display  area  of  a display  device. 

read-only  file.  A file  that  may  be  read  from  but  not 
written  to. 

realize.  To  cause  the  system  to  ensure,  wherever 
possible,  that  the  physical  color  table  of  a device  is  set  to 
the  closest  possible  match  in  the  logical  color  table. 

recursive  routine.  A routine  that  can  call  itself  or  be 
called  by  another  routine  called  by  the  recursive  routine. 

reentrant.  The  attribute  of  a program  or  routine  that 
allows  the  same  copy  of  the  program  or  routine  to  be 
used  concurrently  by  two  or  more  tasks. 

reference  phrase.  A word  or  phrase  that  is  emphasized 
in  a device-dependent  manner  to  inform  the  user  that 
additional  information  for  the  word  or  phrase  is 
available. 

reference  phrase  help.  Provides  help  information  for  a 
selectable  word  or  phrase. 

refresh.  To  update  a window,  with  changed  information, 
to  its  current  status. 

region.  A clipping  boundary  in  device  space. 

register.  A storage  device  having  a specified  storage 
capacity  such  as  a bit,  byte,  or  computer  word,  and 
usually  intended  for  a special  purpose. 

remote  file  system.  A file-system  driver  that  gains 
access  to  a remote  system  without  a block  device  driver. 

resource.  The  means  of  providing  extra  information 
used  in  the  definition  of  a window.  A resource  can 
contain  definitions  of  fonts,  templates,  accelerators,  and 
mnemonics;  the  definitions  are  held  in  a resource  file. 

resource  file.  A file  containing  information  used  in  the 
definition  of  a window.  Definitions  can  be  of  fonts, 
templates,  accelerators,  and  mnemonics. 

restore.  T o return  a window  to  its  original  size  or 
position  following  a sizing  or  moving  action. 

retained  graphics.  Graphic  primitives  that  are 
remembered  by  the  Presentation  Interface  after  they 
have  been  drawn.  Contrast  with  nonretained  graphics. 

return  code.  (1)  A code  used  to  influence  the  execution 
of  succeeding  instructions.  (2)  A value  returned  to  a 
program  to  indicate  the  results  of  an  operation 
requested  by  that  program. 

reverse  video.  A form  of  alphanumeric  highlighting  for  a 
character,  field,  or  cursor,  in  which  its  color  is 
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exchanged  with  that  of  its  background.  For  example, 
changing  a red  character  on  a black  background  to  a 
black  character  on  a red  background. 

RGB.  Red-green-blue.  For  example,  “RGB  display”. 

roman.  Relating  to  a type  style  with  upright  characters. 

root  segment.  In  a hierarchical  database,  the  highest 
segment  in  the  tree  structure. 

run  time.  (1)  Any  instant  at  which  a program  is  being 
executed.  (2)  The  time  during  which  an  instruction  in  an 
instruction  register  is  decoded  and  performed. 

s 

SAA.  Systems  Application  Architecture. 

scheduler.  A computer  program  designed  to  perform 
functions  such  as  scheduling,  initiation,  and  termination 
of  jobs. 

screen.  The  physical  surface  of  a work  station  or 
terminal  upon  which  information  is  presented  to  users. 

screen  device  context.  A logical  description  of  a data 
destination  that  is  a particular  window  on  the  screen. 

See  also  device  context. 

SCREENS.  Character-device  name  reserved  for  the 
display  screen. 

scroll  bar.  A control  window,  horizontally  or  vertically 
aligned,  that  allows  the  user  to  scroll  additional  data  into 
an  associated  panel  area. 

scrollable  entry  field.  An  entry  field  larger  than  the 
visible  field. 

scrollable  selection  field.  A selection  field  that  contains 
more  choices  than  are  visible. 

scrolling.  Moving  a display  image  vertically  or 
horizontally  in  a manner  such  that  new  data  appears  at 
one  edge,  as  existing  data  disappears  at  the  opposite 
edge. 

secondary  window.  A type  of  window  associated  with 
the  primary  window  in  a dialog.  A secondary  window 
begins  a secondary  and  parallel  dialog  that  runs  at  the 
same  time  as  the  primary  dialog. 

sector.  An  addressable  subdivision  of  a track  used  to 
record  one  block  of  program  code  or  data  on  a disk  or 
diskette. 

segment.  See  graphics  segment. 

segment  attributes.  Attributes  that  apply  to  the  segment 
as  an  entity,  as  opposed  to  the  individual  primitives 
within  the  segment.  For  example,  the  visibility  or 
detectability  of  a segment. 

segment  chain.  All  segments  in  a graphics  presentation 
space  that  are  defined  with  the  ’chained'  attribute. 
Synonym  for  picture  chain. 

segment  priority.  The  order  in  which  segments  are 
drawn. 


segment  store.  An  area  in  a normal  graphics 
presentation  space  where  retained  graphics  segments 
are  stored. 

select.  To  mark  or  choose  an  item.  Note  that  select 
means  to  mark  or  type  in  a choice  on  the  screen;  enter 
means  to  send  all  selected  choices  to  the  computer  for 
processing. 

select  button.  The  button  on  a pointing  device,  such  as 
a mouse,  that  is  pressed  to  select  a menu  choice.  Also 
known  as  button  1. 

selection  cursor.  A type  of  cursor  used  to  indicate  the 
choice  or  entry  field  users  want  to  interact  with.  It  is 
represented  by  highlighting  the  item  that  it  is  currently 
positioned  on. 

selection  field.  A field  containing  a list  of  choices  from 
which  the  user  can  select  one  or  more. 

semaphore.  An  object  used  by  multi-threaded 
applications  for  signalling  purposes  and  for  controlling 
access  to  serially  reusable  resources. 

separator.  See  panel  body  area  separator. 

serial  dialog  box.  See  modal  dialog  box. 

serialization.  The  consecutive  ordering  of  items. 

serialize.  To  ensure  that  one  or  more  events  occur  in  a 
specified  sequence. 

serially  reusable  resource  (SRR).  A logical  resource  or 
object  that  can  be  accessed  by  only  one  task  at  a time. 

session.  A routing  mechanism  for  user  interaction  via 
the  console;  a complete  environment  that  determines 
how  an  application  runs  and  how  users  interact  with  the 
application.  OS/2  can  manage  more  than  one  session  at 
a time,  and  more  than  one  process  can  run  in  a session. 
Each  session  has  its  own  set  of  environment  variables 
that  determine  where  OS/2  looks  for  dynamic-link 
libraries  and  other  important  files. 

shadow  box.  The  area  on  the  screen  that  follows  mouse 
movements  and  shows  what  shape  the  window  will  take 
if  the  mouse  button  is  released. 

shared  data.  Data  that  isusedbytwoor  more 
programs. 

shared  memory.  Memory  that  is  used  by  two  or  more 
programs. 

shear.  The  tilt  of  graphics  text  when  each  character 
leans  to  the  left  or  right  while  retaining  a horizontal 
baseline. 

shell.  (1)  A software  interface  between  a user  and  the 
operating  system  of  a computer.  Shell  programs 
interpret  commands  and  user  interactions  on  devices 
such  as  keyboards,  pointing  devices,  and  touch-sensitive 
screens,  and  communicate  them  to  the  operating  system. 
(2)  Software  that  allows  a kernel  program  to  run  under 
different  operating-system  environments. 

Shutdown.  The  procedure  required  before  the  computer 
is  switched  off  to  ensure  that  data  is  not  lost. 


Glossary  X-11 


sibling  processes.  Child  processes  that  have  the  same 
parent  process. 

sibling  windows.  Child  windows  that  have  the  same 
parent  window. 

slider  box.  An  area  on  the  scroll  bar  that  indicates  the 
size  and  position  of  the  visible  information  in  a panel 
area  in  relation  to  the  information  available.  Also  known 
as  thumb  mark. 

source  file.  A file  that  contains  source  statements  for 
items  such  as  high-level  language  programs  and  data 
description  specifications. 

source  statement.  A statement  written  in  a 
programming  language. 

specific  dynamic-link  module.  A dynamic-link  module 
created  for  the  exclusive  use  of  an  application. 

spline.  A sequence  of  one  or  more  Bezier  curves. 

spooler.  A program  that  intercepts  the  data  going  to 
printer  devices  and  writes  it  to  disk.  The  data  is  printed 
or  plotted  when  it  is  complete,  and  the  required  device  is 
available.  The  spooler  prevents  output  from  different 
sources  from  being  intermixed. 

stack.  A list  constructed  and  maintained  so  that  the  next 
data  element  to  be  retrieved  is  the  most  recently  stored. 
This  method  is  characterized  as  last-in-first-out  (LIFO). 

standard  window.  A collection  of  window  elements  that 
form  a panel.  The  standard  window  can  include  one  or 
more  of  the  following  window  elements:  sizing  borders, 
system  menu  icon,  title  bar,  maximize/minimize/restore 
icons,  action  bar  and  pull-downs,  scroll  bars,  and  client 
area. 

static  control.  The  means  by  which  the  application 
presents  descriptive  information  (for  example,  headings' 
and  descriptors)  to  the  user.  The  user  cannot  change 
this  information. 

static  storage.  (1)  A read/write  storage  unit  in  which 
data  is  retained  in  the  absence  of  control  signals.  Static 
storage  may  use  dynamic  addressing  or  sensing  circuits. 
(2)  Storage  other  than  dynamic  storage. 

style.  See  window  style. 

suballocation.  The  allocation  of  a part  of  one  extent  for 
occupancy  by  elements  of  a component  other  than  the 
one  occupying  the  remainder  of  the  extent. 

subdirectory.  In  an  IBM  personal  computer,  a file 
referred  to.  in  a root  directory  that  contains  the  names  of 
other  files  stored  on  the  diskette  or  fixed  disk. 

swapping.  (1)  A process  that  interchanges  the  contents 
of  an  area  of  real  storage  with  the  contents  of  an  area  in 
auxiliary  storage.  (2)  In  a system  with  virtual  storage,  a 
paging  technique  that  writes  the  active  pages  of  a job  to 
auxiliary  storage  and  reads  pages  of  another  job  from 
auxiliary  storage  into  real  storage.  (3)  The  process  of 
temporarily  removing  an  active  job  from  main  storage, 
saving  it  on  disk,  and  processing  another  job  in  the  area 
of  main  storage  formerly  occupied  by  the  first  job. 

switch.  (1)  An  action  that  moves  the  input  focus  from 
one  area  to  another.  This  can  be  within  the  same 


window  or  from  one  window  to  another.  (2)  In  a 
computer  program,  a conditional  instruction  and  an 
indicator  to  be  interrogated  by  that  instruction.  (3)  A 
device  or  programming  technique  for  making  a selection, 
for  example,  a toggle,  a conditional  jump. 

switch  list.  See  Task  List. 

symbolic  identifier.  A text  string  that  equates  to  an 
integer  value  in  an  include  file,  that  is  used  to  identify  a 
programming  object. 

synchronous.  Pertaining  to  events  or  operations  that 
are  predictable  or  occur  at  the  same  time.  See  also 
asynchronous. 

System  Menu.  In  PM,  the  pull-down  in  the  top  left  corner 
of  a window  that  allows  it  to  be  moved  and  sized  with  the 
keyboard. 

system  queue.  This  is  the  master  queue  for  all  pointer 
device  or  keyboard  events. 

Systems  Application  Architecture  (SAA).  A formal  set  of 
rules  that  enables  applications  to  be  run  without 
modification  in  different  computer  environments. 

T 

tag.  One  or  more  characters  attached  to  a set  of  data 
that  defines  the  formatting  or  other  characteristics  of  the 
set,  including  its  definition. 

Task  List.  In  PM,  the  list  of  programs  that  are  active. 

The  list  can  be  used  to  switch  to  a program  and  to  stop 
programs. 

template.  An  ASCII-text  definition  of  an  action  bar  and 
pull-down  menu,  held  in  a resource  file,  or  as  a data 
structure  in  program  memory. 

text.  Characters  or  symbols. 

text  cursor.  A symbol  displayed  in  an  entry  field  that 
indicates  where  typed  input  will  appear. 

text  window.  Also  known  as  the  VIO  window. 

text-windowed  application.  The  environment  in  which 
the  operating  system  performs  advanced&hyphn.video 
input  and  output  operations. 

thread.  A unit  of  execution  within  a process.  It  uses  the 
resources  of  the  process. 

thumb  mark.  The  portion  of  the  scroll  bar  that  describes 
the  range  and  properties  of  the  data  that  is  currently 
visible  in  a window.  Also  known  as  a slider  box. 

tilde.  A mark  used  to  denote  the  character  that  is  to  be 
used  as  a mnemonic  when  selecting  text  items  within  a 
menu. 

time  slice.  (1)  An  interval  of  time  on  the  processing  unit 
allocated  for  use  in  performing  a task.  After  the  interval 
has  expired,  processing-unit  time  is  allocated  to  another 
task,  so  a task  cannot  monopolize  processing-unit  time 
beyond  a fixed  limit.  (2)  In  systems  with  time  sharing,  a 
segment  of  time  allocated  to  a terminal  job. 
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title  bar.  The  area  at  the  top  of  a window  that  contains 
the  window  title.  The  title  bar  is  highlighted  when  that 
window  has  the  input  focus.  Contrast  with  panel  title. 

transaction.  An  exchange  between  a workstation  and 
another  device  that  accomplishes  a particular  action  or 
result. 

transform.  (1)  The  action  of  modifying  a picture  by 
scaling,  shearing,  reflecting,  rotating,  or  translating.  (2) 
The  object  that  performs  or  defines  such  a modification; 
also  referred  to  as  a transformation. 

Tree.  In  PM,  the  window  in  the  File  Manager  that  shows 
the  organization  of  drives  and  directories. 

truncate.  (1)  To  end  a computational  process  in 
accordance  with  some  rule.  (2)  To  remove  the  beginning 
or  ending  elements  of  a string.  (3)  To  drop  data  that 
cannot  be  printed  or  displayed  in  the  line  width  specified 
or  available.  (4)  To  shorten  a field  or  statement  to  a 
specified  length. 

u 

unnamed  pipe.  A circular  buffer,  created  in  memory, 
used  by  related  processes  to  communicate  with  one 
another.  Contrast  with  named  pipe. 

update  region.  A system-provided  area  of  dynamic 
storage  containing  one  or  more  (not  necessarily 
contiguous)  rectangular  areas  of  a window,  that  are 
visually  invalid  or  incorrect,  and  therefore  in  need  of 
repainting. 

user  interface.  Hardware,  software,  or  both  that  allows 
a user  to  interact  with  and  perform  operations  on  a 
system,  program,  or  device. 

User  Shell.  A component  of  OS/2  that  uses  a 
graphics-based,  windowed  interface  to  allow  the  user  to 
manage  applications  and  files  installed  and  running 
under  OS/2. 

utility  program.  (1)  A computer  program  in  general 
support  of  computer  processes;  for  example,  a 
diagnostic  program,  a trace  program,  a sort  program. 

(2)  A program  designed  to  perform  an  everyday  task 
such  as  copying  data  from  one  storage  device  to 
another. 

V 

vector  font.  A set  of  symbols,  each  of  which  is  created 
as  a series  of  lines  and  curves.  Synonymous  with 
outline  font.  Contrast  with  image  font. 

VGA.  Video  graphics  array. 

viewing  pipeline.  The  series  of  transformations  applied 
to  a graphic  object  to  map  the  object  to  the  device  on 
which  it  is  to  be  presented. 

viewing  window.  Clipping  boundary  that  defines  the 
visible  part  of  model  space. 

VIO.  Video  Input/Output. 


virtual  memory  (VM).  Addressable  space  that  is 
apparent  to  the  user  as  the  processor  storage  space,  but 
not  having  a fixed  physical  location. 

virtual  storage.  Synonymous  with  virtual  memory. 

visible  region.  A window’s  presentation  space,  clipped 
to  the  boundary  of  the  window  and  the  boundaries  of  any 
overlying  window. 

volume.  (1)  A file-system  driver  that  uses  a block  device 
driver  for  input  and  output  operations  to  a local  or 
remote  device.  (2)  A portion  of  data,  together  with  its 
data  carrier,  that  can  be  handled  conveniently  as  a unit. 

w 

wild-card  character.  The  global  file-name  characters 
asterisk  (*)  and  question  mark  (?). 

window.  A rectangular  area  of  the  screen  with  visible 
boundaries  within  which  information  is  displayed.  A 
window  can  be  smaller  than  or  the  same  size  as  the 
screen.  Windows  can  appear  to  overlap  on  the  screen. 

window  class.  The  grouping  of  windows  whose 
processing  needs  conform  to  the  services  provided  by 
one  window  procedure. 

window  coordinates.  The  means  by  which  a window 
position  or  size  is  defined;  measured  in  device  units,  or 
pels. 

window  procedure.  Code  that  is  activated  in  response 
to  a message.  The  procedure  controls  the  appearance 
and  behavior  of  its  associated  windows. 

window  rectangle.  The  means  by  which  the  size  and 
position  of  a window  is  described  in  relation  to  the 
desktop  window. 

window  style.  The  set  of  properties  that  influence  how 
events  related  to  a particular  window  will  be  processed. 

workstation.  A display  screen  together  with  attachments 
such  as  a keyboard,  a local  copy  device,  or  a tablet. 

world  coordinates.  Application-convenient  coordinates 
used  for  drawing  graphics. 

world-coordinate  space.  Coordinate  space  in  which 
graphics  are  defined  before  transformations  are  applied. 

WYSIWYG.  What  You  See  Is  What  You  Get.  A capability 
that  enables  text  to  be  displayed  on  a screen  in  the  same 
way  it  will  be  formatted  on  a printer. 

z 

z-order.  The  order  in  which  sibling  windows  are 
presented.  The  topmost  sibling  window  obscures  any 
portion  of  the  siblings  that  it  overlaps;  the  same  effect 
occurs  down  through  the  order  of  lower  sibling  windows. 

zooming.  In  graphics  applications,  the  process  of 
increasing  or  decreasing  the  size  of  picture. 


Glossary  X-13 


X-14  PM  Programming  Reference 


Index 


A 

ABB_*  values  5-405,  5-463 
ACCEL  A-1 
accelerator  table 
copy  8-37 
create  8-44 
destroy  8-98 
load  8-234 
query  8-291 
set  8-439 
translate  8-550 
ACCELTABLE  A-1 
ACCELTABLE  statement  32-9 
Access  a DRAGINFO  Structure  3-26 
Access  Drag  Information  3-4 
Add  Atom  8-7 
Add  Switch  Entry  8-9 
Add  Text  to  DDF  Buffer  4-39 
additional  metrics  F-9 
addressing  elements  in  arrays  1-5 
alarm  sound  8-11 
Allocate  DRAGINFO  Structure  3-7 
Allocate  DRAGTRANSFER  Structures  3-9 
AM_*  values  5-228,  5-401 
Animate  Palette  5-8 
application-supplied  functions  10-1 
Applications 

Windowed  PM  34-1 
Arabic  text  5-435 
arc 

create  5-199 
full  5-148, 5-189 
partial  5-188 
query  parameters  5-226 
set  current  parameters  5-398 
set  default  parameters  5-460 
Arc  at  a Given  Position  33-3 
Arc  at  Current  Position  33-3 
ARCPARAMS  A-2 
AREABUNDLE  A-2 
areas 

begin  construction  5-13 
construction  of  interior  5-15 
end  construction  5-128 
arrays 

addressing  elements  in  1-5 
convert  5-53, 5-55 
ASCII  8-321,8-459,34-23 
ASCII  MIXED  code  pages  34-23 
Associate  5-11 
Associate  Help  Instance  8-13 
ASSOCTABLE  statement  32-10 
ATOM  A-2 

attribute  primitive  type  5-404 
attribute  primitive  types  5-462 
attribute  values 

character  5-404, 5-462 
image  5-405, 5-463 
line  5-404, 5-462 
marker  5-405, 5-463 
pattern  (area)  5-405,  5-463 


attributes 

character-set  5-443 
color  5-453 

cosmetic  line  width  5-498 
foreground  color  mix  5-511 
geometric  line  width  5-500 
line  type  5-495 
line  width  5-498 
marker  box  5-504 
marker  set  5-506 
marker  symbol  5-503 
pattern  5-522 
pattern  set  5-526 
query  mode  5-228 
restore  saved  5-217 
segment  5-539 
set  5-404 
set  default  5-462 
set  line-end  5-491 
set  line-join  5-493 
specify  mode  5-401 

ATTR_*  values  5-304,  5-351 , 5-488,  5-538 

B 

background 

query  color  5-231,5-232 
query  color-mixing  mode  5-232 
query  mix  5-232 
BANDRECT  A-2 
BA_*  values  5-13 
BBO_*  values  5-24,  5-1 13,  5-568 
BDS_*  values  13-3 
Begin  Area  5-13,  33-3 
Begin  Definition  List  4-2 
Begin  Dragging  Files  3-16 
Begin  Element  5-17,  33-4 
Begin  Image  at  Current  Position  33-5 
Begin  Image  at  Given  Position  33-5 
Begin  Paint  8-18 
Begin  Path  5-19,  33-5 
Begin  Window  Enumeration  8-16 
Bezier  Curve  at  Current  Portion  33-6 
Bezier  Curve  at  Given  Position  33-6 
Bezier  splines,  create  5-215 
Bit  Bit  5-23 
bit  maps 

color  5-25,5-114,5-569 

copy  rectangle  of  image  data  5-23,  5-567 

create  5-71 

data  D-1 

delete  5-90 

draw  8-118 

example  D-1 

file  format  D-2 

get  system  8-194 

information  tables  D-1 

load  5-161 

monochrome  5-25,  5-1 14,  5-569 
query  bits  5-233 
query  device  formats  5-280 
query  dimension  5-236 
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bit  maps  (continued) 
query  handle  5-239 
query  info-header  5-237 
query  number  of  local  identifiers  5-329 
query  parameters  5-240 
query  set  identifiers  5-359 
set  as  currently  selected  5-418 
set  bits  5-420 
set  identifier  5-425 
standard  formats  D-1 

transfer  data  from  application  storage  5-420 
bit-map  tag 
delete  5-106 
Bitblt  33-7 
BITMAPINFO  A-3 
BITMAPINFOHEADER  A-6 
BITMAPINFOHEADER2  A-6 
BITMAPINF02  A-3 
bits 

draw  5-112 

BKM_CALCPAGERECT  25-4 
BKM_DELETEPAGE  25-5 
BKMJNSERTPAGE  25-6 
BKMJNVALIDATETABS  25-7 
BKM_QUERYPAGECOUNT  25-7 
BKMQUERYPAGEDATA  25-8 
BKMQUERYPAGEID  25-9 
BKM_QUERYPAGESTYLE  25-10 
BKM_QUERYPAGEWINDOWHWND  25-10 
BKM_QUERYSTATUSLINETEXT  25-11 
BKM_QUERYTABBITMAP  25-12 
BKM_QUERYTABTEXT  25-12 
BKM_SETDIMENSIONS  25-13 
BKM_SETNOTEBOOKCOLORS  25-14 
BKM_SETPAGEDAT  A 25-14 
BKM_SETPAGEWINDOWHWND  25-15 
BKM_SETSTATUSLINETEXT  25-16 
BKM_SETTABBITMAP  25-16 
BKM_SETTABTEXT  25-17 
BKM_TURNTOPAGE  25-18 
BKS_*  values  25-1 
BMSG_*  values  8-20 
BM_CLICK  13-5 
BM_QUERYCHECK  13-6 
BM_QUERYCHECKINDEX  13-6 
BM_QUERYHILITE  13-7 
BM_SETCHECK  13-7 
BM_SETDEFAULT  13-8 
BM_SETHILITE  13-9 
BM_*  values  5-232,  5-415 
BN_*  values  13-3 
BOOKTEXT  A-9 
BOOKTEXT  data  structure  A-9 
BOOL  A-9 
Box  5-28 
draw  5-28 

Box  at  Current  Position  33-8 

Box  at  Given  Position  33-8 

Broadcast  Message  8-20 

BS_*  values  13-1 

BTNCDATA  A-9 

button  control  data  13-2 

button  control  styles  13-1 

button  control  window  processing  13-1 

button  filtering  constants  8-183 

BYTE  A-10 


c 

C language  1-1 

Calculate  Frame  Rectangle  8-22 
Call  Message  Filter  8-24 
Call  Segment  33-9 
Call  Segment  Matrix  5-31 
Cancel  Shutdown  8-26 
CAPS_*  values  2-15 
CATCHBUF  A-10 
CA_*  values  A-17 

column  headings  A-19 
drawing  and  painting  A-18 
icons  or  bit  maps  A-17 
ordered  target  emphasis  A-18 
title  attributes  A-18 
title  position  A-18 
titles  A-18 

CBB_*  values  5-404,  5-462 
CBMJHILITE  19-5 
CBMJSLISTSHOWING  19-5 
CBM_SHOWLIST  19-6 
CBM_*  values  5-71 
CBN_*  values  19-3 
CBS_*  values  19-1 
CCS_*  values 

selection  types  24-3 
styles  24-2 
CDATE  A-10 
CELL  A-10 
CFA_*  values  A-39 

column  attributes  A-40 
data  types  A-39 

horizontal  column  heading  position  A-41 
horizontal  data  position  A-40 
icon  or  bit  map  data  A-40 
prevention  of  direct  editing  of  a column 
heading  A-40 

vertical  column  heading  position  A-40 
vertical  data  position  A-40 
CFI_*  flags  8-310 
CFI_*  values  8-449 
CF_*  values  8-449,  28-4 
chain 

draw  5-117 

chained  attribute  for  segments 

modify  (GpiSetSegmentAttrs)  5-539 
Change  Focus  Window  8-160 
Change  Switch  Entry  8-28 
CHAR  A-10 
character 

convert  to  uppercase  8-558 

query  angle  5-244 

query  box  5-246 

query  break  extra  5-248 

query  direction  5-249 

query  extra  5-250 

query  mode  5-251 

query  set  5-252 

query  shear  5-253 

query  string  positions  5-255 

query  string  positions  at  5-257 

set  angle  5-427 

set  box  5-430 

set  break  extra  5-433 

set  direction  5-435 

set  extra  5-438 
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character  (continued) 
set  mode  5-440 
set  set  5-443 
set  shear  5-445 

character  attribute  values  5-404,  5-462 
character  definitions 
font  F-3 

character  direction 
Arabic  text  5-435 
Chinese  text  5-435 
Roman  text  5-435 
character  set  1-6 
Character  String  5-34 

draw  at  current  position  5-34 
draw  at  current  position,  with  controls  5-39 
draw  at  specified  position  5-36 
draw  string  at  specified  position,  with  controls  5-42 
Character  String  At  5-36 
Character  String  at  Current  Position  33-9 
Character  String  at  Given  Position  33-9 
Character  String  Extended  at  Current  Position  33-10 
Character  String  Extended  at  Given  Position  33-10 
Character  String  Move  at  Current  Position  33-1 1 
Character  String  Move  at  Given  Position  33-11 
Character  String  Position  5-39 
Character  String  Position  At  5-42 
CHARBUNDLE  A-11 
CHDIRN_*  values  5-249,  5-435 
check  box  13-1 
Check  Menu  Item  8-32 
Check  Message  Filter  Hook  10-5 
CheckMsgFilterHook  10-5 
Chinese  text  5-435 
CHS_*  values  5-39,  5-42,  5-255,  5-257 
class  9-1 

CLASSDETAILS  A-12 
CLASSINFO  A-11 
clipboard  28-1 
messages  28-1 
query  format  information  8-310 
query  viewer  window  8-313 
set  data  8-449 
clipboard  messages  28-1 
clipping  5-528,  G-1 

segment  chains  5-122 
set  path  5-448 
set  region  5-451 
clipping  boundary  5-486 
clipping  region  8-150 
Close  Clipboard  8-34 
Close  Device  Context  2-2 
Close  Figure  5-45,  33-12 
Close  Profile  6-2 
Close  Segment  5-47 
closed  figure  5-20 

CLR_*  values  5-76,  5-231,  5-262,  5-338,  5-412,  5-453 
CMDSRC_*  values  11-3,  12-27,  12-36,  12-63,  15-21 
CM_ALLOCDETAILFIELDINFO  24-22 
CM_ALLOCRECORD  24-23 
CMARRANGE  24-24 
CM_CLOSEEDIT  24-24 
CM_COLLAPSETREE  24-25 
CM_ERASERECORD  24-26 
CM_EXPANDTREE  24-26 
CM_FILTER  24-27 
CM_FREEDETAILFIELDINFO  24-28 
CM  FREERECORD  24-29 


CM_HORZSCROLLSPLITWINDOW  24-30 
CMJNSERTDETAILFIELDINFO  24-30 
CMJNSERTRECORD  24-31 
CMJNVALIDATEDETAILFIELDINFO  24-33 
CMJNVALIDATERECORD  24-33 
CM_OPENEDIT  24-35 
CM_PAINTBACKGROUND  24-35 
CM_QUERYCNRINFO  24-36 
CM_QUERYDETAILFIELDINFO  24-37 
CMQUERYDRAGIMAGE  24-38 
CM_QUERYRECORD  24-39 
CM_QUERYRECORDEMPHASIS  24-40 
CM_QUERYRECORDFROMRECT  24-41 
CM_QUERYRECORDINFO  24-42 
CM_QUERYRECORDRECT  24-43 
CM_QUERYVIEWPORTRECT  24-43 
CM_REMOVEDETAILFIELDINFO  24-44 
CM^REMOVERECORD  24-45 
CM_SCROLLWINDOW  24-47 
CM_SEARCHSTRING  24-48 
CM_SETCNRINFO  24-49 
CM_SETRECORDEMPHASIS  24-50 
CM_SORTRECORD  24-51 
CM_*  values  5-251 , 5-427,  5-440 
CNRDRAGINFO  A-12 
CNRDRAGINIT  A-12 
CNRDRAWITEMINFO  A-13 
CNREDITDATA  A-14 
CNREDITDATA  data  structure  A-13 
CNRINFO  A-15 
CN_BEGINEDIT  24-8 
CN_COLLAPSETREE  24-9 
CN_CONTEXTM  ENU  24-9 
CN_DRAGAFTER  24-10 
CN_DRAGLEAVE  24-11 
CN_DRAGOVER  24-12 
CN_DROP  24-13 
CN_DROPHELP  24-14 
CN_EMPHASIS  24-15 
CN_ENDEDIT  24-15 
CN_ENTER  24-16 
CNEXPANDTREE  24-17 
CN_HELP  24-17 
CNJNITDRAG  24-18 
CN_KILLFOCUS  24-19 
CN_QUER  YDELT  A 24-19 
CN_REALLOCPSZ  24-20 
CN_SCROLL  24-21 
CN_SETFOCUS  24-21 
CN_*  values 

described  24-8 
code  page 
query  8-314 
set  8-456 

Code  Page  Change  Hook  10-7 
Code  pages  34-1 
ASCII  34-11 
EBCDIC  34-16 
Font  support  34-4 
OS/2  options  for  PM  34-3 
OS/2  support  for  multiple  34-4 
CodePageChangeHook  10-7 
COLOR  A-20 
color  palette  8-362 
color  table  G-1 
create  5-74 

color  table  default  values  5-76 
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colors 

on  monochrome  devices  5-76 

query  5-262 

query  data  5-264 

query  foreground  mix  mode  5-324 

query  index  5-266 

query  nearest  5-327 

query  real  5-343 

query  RGB  5-349 

query  system  8-362 

set  5-453 

set  background  5-412 
set  system  values  8-494 
Combine  Region  5-49 
combo  box  control  data  19-1 
combo  box  control  window  processing  1 9-1 
Comment  5-51, 33-12 
Compare  Strings  8-35 
constant  names  1-1 
constants 

button  filtering  8-183 
container  control  window  processing 
data  structures  24-3 
icon  size,  how  determined  A-17 
mini-icon  size,  how  determined  A-17 
notification  codes  24-8 
notification  messages  24-4 
purpose  24-1 

styles  and  selection  types  24-2 
window  messages  24-22 
window  words  24-1 
container  views  A-16 

contents  and  format  of  dialog  template  32-19 
control  classes  11-2 
control  codes 

Shift  In  (SI)  34-23 
Shift  Out  (SO)  34-23 
control  data  32-22 
Control  Formatting  4-35 
control  statements 
predefined  32-24 
control  window  processing  11-2 
CONVCONTEXT  A-20 
conventions 
Convert  5-53 
Convert  with  Matrix  5-55 
coordinates 
dialog  32-19 

coordinates  for  dialogs  32-19 
Copy  Accelerator  Table  8-37 
Copy  Metafile  5-57 
Copy  Rectangle  8-39 
Correlate  Chain  5-59 
Correlate  From  5-63 
Correlate  Segment  5-67 
cosmetic  line  width 
query  5-311 

Counts  Number  of  Items  in  Listbox  8-330 
CPTEXT  A-21 

Create  a Paragraph  in  DDF  Buffer  4-24 

Create  Accelerator  Table  8-44 

Create  Atom  T able  8-46 

Create  Bit  Map  5-71 

Create  Cursor  8-48 

Create  Dialog  8-50 

Create  Frame  Controls  8-52 

Create  Help  Instance  8-54 


Create  Help  Table  8-56 
Create  Logical  Color  T able  5-74 
Create  Logical  Font  5-78 
Create  Menu  8-58 
Create  Message  Queue  8-60 
Create  Palette  5-81 
Create  Pointer  8-64 
Create  Pointer  Indirect  8-66 
Create  Presentation  Space  5-84 
Create  Region  5-88 
Create  Standard  Window  8-68 
Create  String  Handle  3-5 
Create  Switch  Entry  8-72 
Create  Window  8-74 
Create  Workplace  Object  8-62 
CREATESTRUCT  A-21 
CREA_*  values  5-195 
CRGN_*  values  5-49 
CS_*  values 

window  class  styles  12-1 
CTAB_*  values  5-195 
CTIME  A-22 
current  position 
move  5-173 
query  5-269 

set  to  specified  point  5-458 
cursor 

create  8-48 
destroy  8-101 
hide  8-518 

query  information  8-316 
show  8-518 
CURSORINFO  A-22 
CURSOR_*  values  8-48 
CVR_*  values  12-23 
CVTC_*  values  5-53 
CV_*  values 

CNRINFO  structure  A-16 
SEARCHSTRING  structure  A-115 
view  styles  A-17 

D 

data 

bit  map  D-1 
get  5-150 
put  5-223 

data  area  in  a dialog  template  32-22 
data  format 
image  F-7 
outline  F-8 
data  types  A-1 

graphics  orders  33-1 
implicit  pointer  1-5 
storage  mapping  1-6 
DBCS  8-285 
DBCS  support  34-23 

character-encoding  schemes  34-23 
DBM_*  values  8-118 
DB_*  values  8-121 
DCTL_*  values  5-282,  5-474 
DC_*  values  A-32 
DDEF_*  values  5-195 
DDEINIT  A-23 
DDESTRUCT  A-23 
DDE_*  values  30-1 , 30-2,  30-3,  A-23 
DdfBeginList  4-2 
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DdfBitmap  4-5 
DdfEndList  4-8 
Ddf HyperText  4-10 
Ddflnform  4-13 
Ddflnitialize  4-15 
DdfListltem  4-18 
DdfMetafile  4-21 
DdfPara  4-24 
DdfSetColor  4-26 
DdfSetFont  4-29 
DdfSetFontStyle  4-32 
DdfSetFormat  4-35 
Ddf  SetText  Align  4-37 
DdfT  ext  4-39 

default  colors  13-2,  14-2,  15-3,  16-1,  17-3,  19-2,  20-2, 
22-2,  23-1 

Default  Dialog  Procedure  8-85 
default  dialog  processing  12-70 
default  graphics  character  box 
query  5-275 

default  message  processing  12-1 
default  view  matrix 
query  5-273 

Default  Window  Procedure  8-89 
default  window  processing  11-1 
DEFAULTICON  keyword  32-11 
Define  Hypertext  Link  4-10 
Define  Inform  Link  4-13 
Define  Text  Alignment  4-37 
Delete  Atom  8-91 
Delete  Bit  Map  5-90 
Delete  DRAGINFO  String  Handles  3-10 
Delete  Element  5-92 
Delete  Element  Range  5-94 
Delete  Elements  Between  Labels  5-96 
Delete  Library  8-95 
Delete  Listbox  Item  8-93 
Delete  Metafile  5-98 
Delete  Palette  5-100 
Delete  Procedure  8-96 
Delete  Segment  5-102 
Delete  Segments  5-104 
Delete  Set  Identifier  5-106 
Delete  String  Handle  3-11 
DELETENOTIFY  A-24 
Deregister  Workplace  Object  Class  8-97 
DESKTOP  A-24 
Destroy  Accelerator  Table  8-98 
Destroy  Atom  Table  8-99 
Destroy  Cursor  8-101 
Destroy  Help  Instance  8-102 
Destroy  Message  Queue  8-104 
Destroy  Pointer  8-107 
Destroy  Presentation  Space  5-108 
Destroy  Region  5-110 
Destroy  Window  8-109 
Destroy  Window  Hook  10-8 
Destroy  Workplace  Object  8-106 
DestroyWindowHook  10-8 
detectability  attribute  for  segments 
modify  (GpiSetSegmentAttrs)  5-539 
DevCIoseDC  2-2 
DevEscape  2-4 
DEVESC_*  values  2-4,  2-5 
device  characteristics 
query  2-15 
device  context 


device  context  (continued) 
clear  output  display  5-136 
close  2-2 
create  2-9 
open  2-9 

open  for  a window  8-273 
screen  8-128 
DevOpenDC  2-9 
DEVOPENSTRUC  A-25 
DevPostDeviceModes  2-12 
DevQueryCaps  2-15 
DevQueryDeviceNames  2-21 
DevQueryHardcopyCaps  2-24 
DEV_*  values  2-2,2-10 
DFORM_*  values  5-150,  5-223 
dialog 

create  8-50 
default  procedure  8-85 
dismiss  8-111 
enumerate  item  8-145 
load  8-236 
process  modal  8-287 
query  item  short  8-321 
send  message  to  item  8-435 
set  item  short  8-459 
dialog  item 

query  text  8-323 
query  text  length  8-325 
set  text  8-461 
dialog  points 
map  8-259 

Dialog  Procedure  10-2 
dialog  processing  12-70 
default  12-70 
language  support  12-83 
dialog  template 

data-area  information  32-22 
format  and  contents  32-19 
header  information  32-20 
item  information  32-21 
dialog  window 

destroy  modal  8-1 1 1 
hide  modeless  8-111 
DialogProc  10-2 
dialogs 

define  procedure  10-2 
Direct  Manipulation  for  Files  3-2 
direct  manipulation  messages  29-1 
directives  32-4 
Dismiss  Dialog  8-111 
Dispatch  Message  8-113 
dithered  colors  5-327 
dithering  5-327, 8-494 
DLGC_*  values  12-72 
DLGTEM  PLATE  A-27 
DLGTEMPLATE  statement  32-16 
DLGTITEM  A-27 
DM_DISCARDOBJECT  29-1 
DM_DRAGERROR  29-2 
DM_DRAGFILECOMPLETE  29-2 
DM_DRAGLEAVE  29-3 
DM_DRAGOVER  29-4 
DM_DRAGOVERNOTIFY  29-5 
DM_DROP  29-6 
DMDROPHELP  29-7 
DM_EMPHASIZET  ARGET  29-7 
DM  ENDCONVERSATION  29-8 


DM_FILERENDERED  29-9 
DM_PRINTOBJECT  29-9 
DM_RENDER  29-10 
DM_RENDERCOMPLETE  29-11 
DM_RENDERFILE  29-12 
DM_RENDERPREPARE  29-13 
DM_*  values  5-284,  5-477 
double-byte  character  set  1-6 
double-byte  character  sets  34-23 
Down  cursor  key  8-547 
DO_*  values 

DRAGINFO  data  structure  A-29 

DRAGITEM  data  structure  A-32 
DPC  errors  5-2 
DPDM_*  values  2-13 
DP_*  values  8-124 
Drag  3-12 
drag  Information 

access  3-4 
drag  messages  29-1 
DRAGIMAGE  A-28 
DRAGINFO  A-29 
DRAGITEM  A-30 
DRAGTRANSFER  A-32 
Draw  Bit  Map  8-118 
Draw  Bits  5-112 
Draw  Border  8-121 
Draw  Chain  5-117 
Draw  Dynamics  5-119 
Draw  From  5-121 
draw  mode  5-47 
Draw  Pointer  8-124 
Draw  Polygons  5-207 
Draw  Seg  ment  5-1 23 
Draw  Text  8-126 
Draw  Tracking  Rectangle  8-546 
draw-and-retain  mode  5-47 
drawing  mode 

draw  5-126,  5-474,  5-478,  5-558 

draw-and-retain  5-126,  5-287,  5-474,  5-478,  5-558 

query  5-284 

retain  5-126,  5-252,  5-287,  5-478,  5-558 

set  5-477 

drawing  orders  33-1 
drawing  process  check  errors  5-2 
DRF_*  values  A-31 
DrgAcceptDroppedFiles  3-2 
DrgAccessDraginfo  3-4 
DrgAddStrHandle  3-5 
DrgAllocDraginfo  3-7 
DrgAllocDragtransfer  3-9 
DrgDeleteDraginfoStrHandles  3-10 
DrgDeleteStrHandle  3-11 
DrgDrag  3-12 
DrgDragFiles  3-16 
DrgFreeDraginfo  3-19 
DrgFreeDragtransfer  3-21 
DrgGetPS  3-22 
DrgPostTransferMsg  3-24 
DrgPushDraginfo  3-26 
DrgQueryDragitem  3-28 
DrgQueryDragjtemCount  3-30 
DrgQueryDragitemPtr  3-31 
DrgQueryNativeRMF  3-32 
DrgQueryNativeRMFLen  3-34 
DrgQueryStrName  3-36 
DrgQueryStrNameLen  3-38 


DrgQueryTrueType  3-40 

DrgQueryTrueTypeLen  3-42 

DrgReleasePS  3-44 

DrgSendTransferMsg  3-45 

DrgSetDraglmage  3-48 

DrgSetDragitem  3-50 

DrgSetDragPointer  3-53 

DrgVerifyNativeRMF  3-55 

DrgVerifyRMF.  3-57 

DrgVerifyTrueType  3-59 

DrgVerifyType  3-61 

DrgVerifyTypeSet  3-63 

DRG_*  values  A-29 

DRIVDATA  A-33 

DRIVPROPS  A-34 

DRM_*  values  A-31 

DRO_*  values  5-28,  5-148 

DRT_*  values  A-30 

DTYP_*  values  8-408 

DT_*  values  8-127,22-1 

Dynamic  Data  Exchange  Initiate  (NLS)  8-78 

dynamic  data  exchange  messages  30-1 

Dynamic  Data  Exchange  Post  Message  (NLS)  8-80 

Dynamic  Data  Exchange  Respond  (NLS)  8-83 

E 

EBCDIC  MIXED  code  pages  34-23 
edit  mode 

query  5-285 
set  5-480 
EDI_*  values  8-145 
EGA  2-19 
Element  5-125 
end  5-130 
query  5-286 
elements 

delete  5-92 

delete  between  labels  5-96 
delete  between  range  5-94 
offset  pointer  5-177 
query  pointer  5-288 
query  type  5-290 
set  pointer  at  label  5-484 
Empty  Clipboard  8-130 
EM_CLEAR  14-4 
EM_COPY  14-4 
EM_CUT  14-5 
EM_PASTE  14-5 
EM_QUERYCHANGED  14-6 
EM_QUERYFIRSTCHAR  14-7 
EM_QUERYREADONLY  14-7 
EM_QUERYSEL  14-8 
EM_SETFIRSTCHAR  14-8 
EM_SETINSERTMODE  14-9 
EM_SETREADONLY  14-10 
EM_SETSEL  14-10 
EM_SETTEXTLIMIT  14-11 
Enable  Control  of  Button  Id  8-131 
Enable  Menu  Item  8-132 
Enable  Physical  Input  8-134 
Enable  Window  Update  8-137 
encapsulation  9-1 
End  Area  5-128,  33-13 
End  Definition  List  4-8 
End  Element  5-130,  33-13 
End  Image  33-13 


X-20  PM  Programming  Reference 


End  of  Symbol  Definition  33-14 

End  Paint  8-141 

End  Path  5-132,33-14 

End  Prolog  33-14 

End  Window  Enumeration  8-139 

ENDFONT  structure  F-1 

Enter  key  8-547 

entry  field  control  data  14-2 

entry  field  control  window  processing  14-1 

ENTRYFDATA  A-34 

Enumerate  Clipboard  Formats  8-143 

Enumerate  Dialog  Item  8-145 

Enumerate  Object  Classes  8-147 

EN_*  values  14-3, 18-3 

EQRGN_*  values  5-134 

Equal  Rectangle  8-148 

Equal  Region  5-134 

Erase  5-136 

ERRINFO  A-35 

Error  Segment  Data  5-138 

error  severities  1-2 

error  state 

get  last  one  8-178 
error-information  block  8-165 
ERRORID  A-35 
errors 

codes  B-1 

drawing  process  check  5-2 
explanations  C-1 
get  information  8-175 
severities  of  1-2 
Esc  key  8-547 
Escape  2-4, 33-15 
ESCSETMODE  A-35 
ES_*  dbcsvals  14-2 
ES_*  values  14-1 
Exclude  Clip  Rectangle  5-140 
Exclude  Update  Region  8-150 
Extended  Escape  33-15 

F 

FACENAMEDESC  A-35 
FATTRS  A-36 

FATTR_FONTUSE_*  values  A-38 
FATTR_SEL_*  values  A-37 
FATTR_TYPE_*  values  A-38 
FCF_*  frame  styles  8-424 
FCF_*  values  15-1 
FC_*  values  8-160 
FDATE  A-38 
FDM_ERROR  12-73 
FDM_FILTER  12-74 
FDM_  VALIDATE  12-74 
FDS_*  values  A-42 
FFDESCS  A-39 
FFDESCS2  A-39 
FF_*  indicators  8-400 
FF_*  values  5-144 
FID_*  values  15-1,  23-1 
FIELDINFO  A-39 
FIELDINFOINSERT  A-41 
FIELDINFOINSERT  data  structure  A-41 
file  dialog  12-73 
file  format 
file  formats 
bit  maps  D-2 


file  formats  (continued) 
icon  file  D-2 
pointer  D-2 
FILEDLG  A-42 
FILEFINDBUF4  A-46 
Fill  Path  5-142,  33-16 
Fill  Rectangle  8-154 
Fillet  at  Current  Position  33-16 
Fillet  at  Given  Position  33-16 
Find  Atom  8-156 
Find  Word  Hook  10-9 
FindWordHook  10-9 
FIXED  A-46 
Fl_*  values  15-18 
Flash  Window  8-158 
flashing 

start  8-158 
stop  8-158 
flipping  bits  8-211 
Flood  Fill  5-144 
FM_*  values  5-324,  5-510 
FNTF_*  values  A-49 
FNTM_FACENAMECHANGED  12-76 
FNTM_FILTERLIST  12-77 
FNTMPOINTSIZECHANGED  12-78 
FNTM_STYLECHANGED  12-78 
FNTM_UPDATE  PREVIEW  12-79 
FNTS_*  values  A-48 
FOCAMETRICS  structure  F-2 
focus 

change  window  8-160 
query  8-327 
set  window  8-464 
FOLDERDATA  A-46 
font  character  definitions  F-3 
font  definition  header  F-4 
font  dialog  12-75 
font  directory  F-1 1 
font  metrics  F-1 
font-file  format  F-1 

FONTDEFINITIONHEADER  structure  F-4 
FONTDLG  A-47 
FONTMETRICS  A-52 
fonts 

create  logical  definition  5-78 
definition  of  terms  F-12 
Japanese  34-23 
load  5-163 
load  public  5-167 

outline  5-427,  5-430,  5-433,  5-438,  5-445 
query  5-299 
query  action  5-294 
query  face  string  5-292 
query  logical  5-315 
query  metrics  5-297 
query  number  of  local  identifiers  5-329 
query  set  identifiers  5-359 
query  width  table  5-372 
raster  5-427,  5-430,  5-433,  5-438,  5-445,  5-522 
unload  5-563 
unload  public  5-565 
fonts  supplied  with  OS/2  E-1 
FONTSIGNATURE  structure  F-1 
FONT_*  values  5-78 
format 

font-file  F-1 

format  and  contents  of  dialog  template  32-19 
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FPATH_*  values  5-142,  5-191 
frame  control  data  15-3 
frame  control  window  processing  15-1 
Frame  Region  5-146 
FRAMECDATA  A-60 
Free  DRAGINFO  Structure  3-19 
Free  DRAGTRANSFER  Storage  3-21 
Free  Error  Information  8-165 
Free  File  Icon  8-168 
Free  Standard  File  Dialog  File  List  8-166 
FS_*  values  15-3 
FTIME  A-61 
Full  Arc  5-148 
create  5-148 

Full  Arc  at  Current  Position  33-17 
Full  Arc  at  Given  Position  33-17 
function  descriptions 
conventions  used  1-1 
functions 

supplied  by  applications  10-1 


G 

GARC  33-3 

GBAR  33-3 

GBBLT  33-7 

GBEL  33-4 

GBEZ  33-6 

GBIMG  33-5 

GBIT1  33-1 

GBIT16  33-1 

GBIT2  33-1 

GBIT32  33-1 

GBIT4  33-1 

GBIT5  33-1 

GBIT6  33-1 

GBIT7  33-1 

GBIT8  33-1 

GBOX  33-8 

GBPTH  33-5 

GCALLS  33-9 

GCARC  33-3 

GCBEZ  33-6 

GCBIMG  33-5 

GCBOX  33-8 

GCCHST  33-9 

GCCHSTE  33-10 

GCCHSTM  33-11 

GCFARC  33-17 

GCFLT  33-16 

GCHAR  33-1 

GCHST  33-9 

GCHSTE  33-10 

GCHSTM  33-11 

GCLFIG  33-12 

GCLINE  33-18 

GCMRK  33-18 

GCOMT  33-12 

GCPARC  33-20 

GCRLINE  33-22 

GCSFLT  33-50 

GDELPOINT  33-1 

GEAR  33-13 

GEEL  33-13 

GEESCP  33-15 

GEIMG  33-13 

general  window  styles  12-1 


geometric  line  width  5-312 
GEPROL  33-14 
GEPTH  33-14 
GESCP  33-15 
GESD  33-14 

Get  Clipped  Presentation  Space  8-169 
Get  Current  Time  8-171 
Get  Data  5-150 
Get  Dialog  Message  8-172 
Get  Drag  Presentation  Space  3-22 
Get  Dragged  Object  Count  3-30 
Get  DRAGITEM  Structure  3-28 
Get  Error  Information  8-175 
Get  Format  of  a Dragged  Object  3-32 
Get  Key  State  8-176 
Get  Last  Error  8-178 
Get  Maximum  Position  8-179 
Get  Message  8-183 
Get  Minimum  Position  8-181 
Get  Multiple  Windows  From  Identities  8-266 
Get  Next  Window  8-186 
Get  Physical  Key  State  8-188 
Get  Pointer  to  DRAGITEM  Structure  3-31 
Get  Presentation  Space  8-190 
Get  Screen  Presentation  Space  8-192 
Get  String  Contents  3-36 
Get  String  Length  3-38 
Get  String  Length  for  Native  RMF  of  Dragged 
Object  3-34 

Get  String  Length  for  True  Type  of  Dragged  Object  3-42 

Get  System  Bit  Map  8-194 

Get  True  Type  of  Dragged  Object  3-40 

GFARC  33-17 

GFIXED  33-2 

GFIXEDS  33-2 

GFLT  33-16 

GFPTH  33-16 

GHBITMAP  33-2 

GIMD  33-17 

GINDATT  33-2 

GINDEX3  33-2 

GLBL  33-18 

GLENGTH1  33-2 

GLENGTH2  33-2 

GLINE  33-18 

GLONG  33-2 

GMPTH  33-19 

GMRK  33-18 

GNOP1  33-19 

GOPTH  33-19 

GPARC  33-20 

GpiAnimatePalette  5-8 

GpiAssociate  5-1 1 

GpiBeginArea  5-13 

GpiBeginElement  5-17 

GpiBeginPath  5-19 

GpiBitBIt  5-23 

GpiBox  5-28 

GpiCallSegmentMatrix  5-31 
GpiCharString  5-34 
GpiCharStringAt  5-36 
GpiCharStringPos  5-39 
GpiCharStringPosAt  5-42 
GpiCloseFigure  5-45 
GpiCloseSegment  5-47 
GpiCombineRegion  5-49 
GpiComment  5-51 
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GpiConvert  5-53 
GpiConvertWithMatrix  5-55 
GpiCopyMetaFile  5-57 
GpiCorrelateChain  5-59 
GpiCorrelateFrom  5-63 
GpiCorrelateSegment  5-67 
GpiCreateBitmap  5-71 
GpiCreateLogColorTable  5-74 
GpiCreateLogFont  5-78 
GpiCreatePalette  5-81 
GpiCreatePS  5-84 
GpiCreateRegion  5-88 
GpiDeleteBitmap  5-90 
GpiOeleteElement  5-92 
GpiDeleteElementRange  5-94 
GpiDeleteElementsBetweenLabels  5-96 
GpiDeleteMetaFile  5-98 
GpiDeletePalette  5-100 
GpiDeleteSegment  5-102 
GpiDeleteSegments  5-104 
GpiOeleteSetld  5-106 
GpiDestroyPS  5-108 
GpiDestroyRegion  5-110 
GpiDrawBits  5-112 
GpiDrawChain  5-117 
GpiDrawDynamics  5-119 
GpiDrawFrom  5-121 
GpiDrawSegment  5-123 
GpiElement  5-125 
GpiEndArea  5-128 
GpiEndElement  5-130 
GpiEndPath  5-132 
GpiEqualRegion  5-134 
GpiErase  5-136 
GpiErrorSegmentData  5-138 
GpiExcludeClipRectangle  5-140 
GPIE_*  values  5-138 
GpiFillPath  5-142 
GpiFloodFill  5-144 
GpiFrameRegion  5-146 
GpiFullArc  5-148 
GPIF_*  values  5-533 
GpIGetData  5-150 
Gpilmage  5-153 
GpilntersectClipRectangle  5-155 
GpiLabel  5-157 
GpILIne  5-159 
GpILoadBitmap  5-161 
GpiLoadFonts  5-163 
GpiLoadMetaFlle  5-165 
GpILoadPublicFonts  5-167 
GpIMarker  5-168 
GpiModifyPath  5-170 
GpIMove  5-173 
GpiOffsetCllpReglon  5-175 
GpiOffsetElementPointer  5-177 
GplOffsetReglon  5-179 
GpiOpenSegment  5-181 
GpiOutlinePath  5-184 
GpIPaintReglon  5-186 
GpiPartialArc  5-188 
GpiPathToRegion  5-191 
GpiPlayMetaFlle  5-193 
GpiPointArc  5-199 
GpiPolyFillet  5-201 
GpIPolyFilletSharp  5-204 
GpiPolygons  5-207 


GpIPolyLine  5-209 
GpiPolyLlneDisjoint  5-211 
GpiPolyMarker  5-213 
GpIPolySpllne  5-215 
GpiPop  5-217 
GpIPtlnRegion  5-219 
GpiPtVisible  5-221 
GpIPutData  5-223 
GpIQueryArcParams  5-226 
GpIQueryAttrMode  5-228 
GpiQueryAttrs  5-229 
GpIQueryBackColor  5-231 
GpiQueryBackMIx  5-232 
GpiQueryBItmapBits  5-233 
GpIQueryBitmapDimenslon  5-236 
GpiQueryBItmapHandle  5-239 
GpiQueryBItmapInfoHeader  5-237 
GpIQueryBItmapParameters  5-240 
GpiQueryBoundaryData  5-242 
GpIQueryCharAngle  5-244 
GpIQueryCharBox  5-246 
GpIQueryCharBreakExtra  5-248 
GpIQueryCharDirection  5-249 
GpiQueryCharExtra  5-250 
GpiQueryCharMode  5-251 
GpIQueryCharSet  5-252 
GpIQueryCharShear  5-253 
GpIQueryCharStrlngPos  5-255 
GpiQueryCharStringPosAt  5-257 
GpiQueryClIpBox  5-259 
GpiQueryClipRegion  5-261 
GpiQueryColor  5-262 
GpIQueryColorData  5-264 
GpiQueryColorlndex  5-266 
GpIQueryCp  5-268 
GpIQueryCurrentPositlon  5-269 
GpiQueryDefArcParams  5-270 
GpiQueryDefAttrs  5-271 
GpIQueryDefauItViewMatrix  5-273 
GpiQueryOefCharBox  5-275 
GpIQueryDefTag  5-277 
GpIQueryDefViewingLImlts  5-278 
GpIQueryDevice  5-279 
GpIQueryDeviceBitmapFormats  5-280 
GpIQueryDrawControl  5-282 
GpIQueryDrawIngMode  5-284 
GpiQueryEditMode  5-285 
GpiQueryElement  5-286 
GpIQueryElementPoInter  5-288 
GpiQueryElementType  5-290 
GpiQueryFaceString  5-292 
GpiQueryFontAction  5-294 
GpiQueryFontFileDescriptions  5-295 
GpiQueryFontMetrics  5-297 
GpiQueryFonts  5-299 
GpiQueryFullFontFileDescriptions  5-301 
GpIQueryGraphlcsFleld  5-303 
GpiQuerylnitialSegmentAttrs  5-304 
GpiQueryKemingPairs  5-306 
GpIQueryLlneEnd  5-308 
GpiQueryLlneJoin  5-309 
GpiQueryLineType  5-310 
GpiQueryLineWidth  5-311 
GpiQueryLineWidthGeom  5-312 
GpiQueryLogColorTable  5-313 
GpiQueryLogicalFont  5-315 
GpiQueryMarker  5-317 
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GpiQueryMarkerBox  5-318 
GpiQueryMarkerSet  5-320 
GpiQueryMetaFiieBits  5-321 
GpiQueryMetaFileLength  5-323 
GpiQueryMix  5-324 
GpiQueryModelTransformMatrix  5-325 
GpiQueryNearestColor  5-327 
GpiQueryNumberSetlds  5-329 
GpiQueryPageViewport  5-330 
GpiQueryPalette  5-332 
GpiQueryPalettelnfo  5-333 
GpiQueryPattern  5-335 
GpiQueryPatternRefPoint  5-336 
GpiQueryPatternSet  5-337 
GpiQueryPel  5-338 
GpiQueryPickAperturePosition  5-340 
GpiQueryPickApertureSize  5-341 
GpiQueryPS  5-342 
GpiQueryRealColors  5-343 
GpiQueryRegionBox  5-345 
GpiQueryRegionRects  5-347 
GpiQueryRGBColor  5-349 
GpiQuerySegmentAttrs  5-351 
GpiQuerySegmentNames  5-353 
GpiQuerySegmentPriority  5-355 
GpiQuerySegmentTransformMatrix  5-357 
GpiQuerySetlds  5-359 
GpiQueryStopDraw  5-362 
GpiQueryTag  5-363 
GpiQueryTextAlignment  5-364 
GpiQueryTextBox  5-365 
GpiQueryViewingLimits  5-368 
GpiQueryViewingTransformMatrix  5-370 
GpiQueryWidthTable  5-372 
GpiRectlnRegion  5-374 
GpiRectVisible  5-376 
GpiRemoveDynamics  5-378 
GpiResetBoundaryData  5-381 
GpiResetPS  5-382 
GpiRestorePS  5-384 
Gpi  Rotate  5-386 
GpiSaveMetaFile  5-389 
GpiSavePS  5-391 
GpiScale  5-393 
GpiSelectPalette  5-396 
GpiSetArcParams  5-398 
GpiSetAttrMode  5-401 
GpiSetAttrs  5-404 
GpiSetBackColor  5-412 
GpiSetBackMix  5-415 
GpiSetBitmap  5-418 
GpiSetBitmapBits  5-420 
GpiSetBitmapDimension  5-423 
GpiSetBitmapId  5-425 
GpiSetCharAngle  5-427 
GpiSetCharBox  5-430 
GpiSetCharBreakExIra  5-433 
GpiSetCharDirection  5-435 
GpiSetCharExtra  5-438 
GpiSetCharMode  5-440 
GpiSetCharSet  5-443 
GpiSetCharShear  5-445 
GpiSetClipPath  5-448 
GpiSetClipRegion  5-451 
GpiSetColor  5-453 
GpiSetCp  5-456 
GpiSetCurrentPosition  5-458 


GpiSetDefArcParams  5-460 
GpiSetDefAttrs  5-462 
GpiSetDefauItViewMatrix  5-467 
GpiSetDefTag  5-470 
GpiSetDefViewingLimits  5-472 
GpiSetDrawControl  5-474 
GpiSetDrawingMode  5-477 
GpiSetEditMode  5-480 
GpiSetElementPointer  5-482 
GpiSetElementPointerAtLabel  5-484 
GpiSetGraphicsField  5-486 
GpiSetlnitialSegmentAttrs  5-488 
GpiSetLineEnd  5-491 
GpiSetLineJoin  5-493 
GpiSetLineType  5-495 
GpiSetLineWidth  5-498 
GpiSetLineWidthGeom  5-500 
GpiSetMarker  5-502 
GpiSetMarkerBox  5-504 
GpiSetMarkerSet  5-506 
GpiSetMetaFileBits  5-508 
GpiSetMix  5-510 

GpiSetModelTransformMatrix  5-513 
GpiSetPageViewport  5-516 
GpiSetPaletteEntries  5-518 
GpiSetPattern  5-521 
GpiSetPatternRefPoint  5-524 
GpiSetPatternSet  5-526 
GpiSetPel  5-528 

GpiSetPickAperturePosition  5-530 

GpiSetPickApertureSize  5-531 

GpiSetPS  5-533 

GpiSetRegion  5-536 

GpiSetSegmentAttrs  5-538 

GpiSetSegmentPriority  5-541 

GpiSetSegmentT ransformMatrix  5-543 

GpiSetStopDraw  5-546 

GpiSetTag  5-548 

GpiSetTextAlignment  5-550 

GpiSetViewingLimits  5-553 

GpiSetViewingT ransformMatrix  5-555 

GpiStrokePath  5-558 

GpiTransiate  5-560 

GpiUnloadFonts  5-563 

GpiUnloadPublicFonts  5-565 

GpiWCBitBIt  5-567 

GPI_*  values  5-196 

GPOINT  33-2 

GPOINTB  33-2 

G POLYS  33-2,  33-20 

GPOP  33-21 

GPSAP  33-23 

GPSBCOL  33-23 

GPSBICOL  33-24 

GPSBMX  33-25 

GPSCA  33-26 

GPSCBE  33-26 

GPSCC  33-27 

GPSCD  33-28 

GPSCE  33-28 

GPSCH  33-30 

GPSCOL  33-31 

GPSCP  33-32 

GPSCR  33-29 

GPSCS  33-30 

GPSECOL  33-32 

GPSFLW  33-33 
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GPSIA  33-35 
GPSICOL  33-34 
GPSLE  33-36 
GPSLJ  33-36 
GPSLT  33-37 
GPSLW  33-38 
GPSMC  33-39 
GPSMP  33-40 
GPSMS  33-40 
GPSMT  33-41 
GPSMX  33-41 
GPSPIK  33-45 
GPSPRP  33-43 
GPSPS  33-44 
GPSPT  33-44 
GPSSLW  33-46 
GPSTA  33-47 
GPSTM  33-42 
GPSVW  33-48 
GRADIENTL  A-61 
graphics 

orders  33-1 
query  field  5-303 
set  field  5-486 
graphics  orders 
datatypes  33-1 
GREAL  33-2 
GRES_*  values  5-382 
GRLINE  33-22 
GROF  33-2 
GROFUFS  33-2 
GROL  33-2 
GROSOL  33-2 
GROUFS  33-2 
GROUL  33-2 
GSAP  33-23 
GSBCOL  33-23 
GSBICOL  33-24 
GSBMX  33-25 
GSCA  33-26 
GSCBE  33-26 
GSCC  33-27 
GSCD  33-28 
GSCE  33-28 
GSCH  33-30 
GSCOL  33-31 
GSCP  33-32 
GSCPTH  33-31 
GSCR  33-29 
GSCS  33-30 
GSECOL  33-32 
GSFLT  33-50 
GSFLW  33-33 
GSGCH  33-22 
GSHORT  33-2 
GSHORT370  33-2 
GSIA  33-35 
GSICOL  33-34 
GSLE  33-36 
GSLJ  33-36 
GSLT  33-37 
GSLW  33-38 
GSMC  33-39 
GSMP  33-40 
GSMS  33-40 
GSMT  33-41 
GSMX  33-41 


GSPIK  33-45 
GSPRP  33-43 
GSPS  33-44 
GSPT  33-44 
GSSB  33-45 
GSSLW  33-46 
GST  A 33-47 
GSTM  33-42 
GSTR  33-2 
GSTV  33-48 
GSVW  33-48 
GUCHAR  33-2 
GUFIXEDS  33-3 
GULONG  33-3 
GULONG370  33-3 
GUNDF  33-3 
GUNDF1  33-3 
GUSHORT  33-3 
GUSHORT370  33-3 


H 

HAB  A-61 

HACCEL  A-61 

HAPP  A-61 

HATOMTBL  A-61 

HBITMAP  A-61 

HCAPS_*  values  A-62 

HCINFO  A-61 

HDC  A-62 

HDDF  A-62 

header  32-20 

header  files  1-3 

Help  Hook  10-10 

help  manager  messages  31-1 

helper  macros  1-3 

HelpHook  10-10 

HELPINIT  A-62 

HELPTABLE  A-63 

HENUM  A-64 

HEV  A-64 

HFILE  A-64 

HFIND  A-64 

HFM_*  values  10-10 

HIGHERj*  values  5-355,  5-541 

highlight  attribute  for  segments 

modify  (GpiSetSegmentAttrs)  5-539 
HINI  A-64 
HK_*  values  8-466 
HLIB  A-64 

HMERR_*  error  constants  31-4 

HMF  A-64 

HMODULE  A-64 

HMQ  A-64 

HMQ_*  values  8-418 

HMTX  A-64 

HMUX  A-64 

H M_ACTIONBAR_COM  M AND  31-1 
HM_CONTROL  31-1 
HM_CREATE_HELP_TABLE  31-2 
HM_DISMISS_WINDOW  31-2 
HM_DISPLAY_HELP  31-3 
HM_ERROR  31-4 
HM_EXT_HELP  31-5 
HM_EXT_HELP_UNDEFINED  31-6 
HM_GENERAL_HELP  31-6 
HM_GENERAL_HELP_UNDEFINED  31-7 
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HM_HELPSUBITEM_NOT_FOUND  31-8 
HM_HELP_CONTENTS  31-7 
HM_HELP_INDEX  31-8 
HMJNFORM  31-9 
HM_IN  VALI  DATE_DDF_DAT  A 31-10 
HM_KEYS_HELP  31-10 
HM_LOAD_HELP_TABLE  31-11 
HM_NOTIFY  31-12 
HM_QUERY  31-13 
HM_QUERY_DDF_DATA  31-14 
HM_QUERY_KEYS_HELP  31-14 
HM_REPLACE_HELP_FOR_HELP  31-15 
HM_REPLACE_USING_HELP  31-15 
HM_SET_ACTIVE_WINDOW  31-16 
HM_SET_COVERPAGE_SIZE  31-17 
HM_SET_HELP_LIBRARY_NAME  31-17 
HM_SET_HELP_WINDOW_TITLE  31-18 
HM_SET_OBJCOM_WINDOW  31-18 
HM_SET_SHOW_PANEL_ID  31-19 
HM_SET_USERDAT  A 31-19 
HM_TUTORIAL  31-20 

HM_UPDATE_OBJCOM_WINDOW_CHAIN  31-21 

HOBJECT  A-64 

hook 

change  code  page  10-7 
find  word  10-9 
help  requests  10-10 
input  10-8, 10-13 
message  filter  10-20 
release  8-418 
send  message  10-23 
set  8-466 
hooks  10-1 
HPAL  A-64 
HPOINTER  A-64 
HPROC  A-64 
HPROGARRAY  A-64 
H PROGRAM  A-65 
HPS  A-65 
HRGN  A-65 
HRGN_*  values  5-451 
HSEM  A-65 
HSPL  A-65 
HSTR  A-65 
HSVWP  A-65 
HSWITCH  A-65 
HT_*  values  12-37 
HWND  A-65 

HWND_*  values  8-1 1 , 8-50,  8-52,  8-58,  8-1 15,  8-236, 
8-244,  8-260,  8-362,  8-506 

I 

IBB_*  values  5-405,  5-463 
icon 

destroy  8-107 
icon  file  format  D-2 
icon  size,  how  determined  A-17 
ICONINFO  A-65 
IconPos  A-66 
Image  5-153 
draw  5-153 

image  attribute  values  5-405,  5-463 
Image  Data  33-17 
IMAGEBUNDLE  A-66 
Implicit  Pointer  1-1 
implicit  pointer  data  types  1-5 


In  Send  Message  8-201 
Inflate  Rectangle  8-197 
information  tables 
bit  map  D-1 
inheritance  9-1 
initialization  file  H-1 
Initialize  8-199 
Initialize  DDF  Area  4-15 
initialize  Presentation  Interface  8-199 
Input  Hook  10-13 
InputHook  10-13 
Insert  List  Item  4-18 
Insert  Listbox  Item  8-203 
interchange  file  format  G-1 
Intersect  Clip  Rectangle  5-155 
Intersect  Rectangle  8-205 
Invalidate  Rectangle  8-207 
Invalidate  Region  8-209 
Invert  Rectangle  8-211 
IPT  A-66 
Is  Child  8-213 
Is  Control  Enabled  8-214 
Is  Menu  Item  Checked  8-216 
Is  Menu  Item  Enabled  8-218 
Is  Menu  Item  Valid  8-220 
Is  Physical  Input  Enabled  8-222 
Is  Rectangle  Empty  8-223 
Is  Thread  Active  8-224 
Is  Window  8-226 
items  in  a dialog  template  32-21 

J 

Japanese  fonts  34-23 
Journal  Playback  Hook  10-14 
Journal  Record  Hook  10-15 
JournalPlaybackHook  10-14 
JournalRecordHook  10-15 
JRN_*  values  12-39 

K 

kanji  34-23 
KC_*  values  12-24 
kerning  A-60 

device  support  2-18 
enable  A-38 
number  of  pairs  A-60 
query  pairs  5-306 
kerning  pair  table  F-8 
KERNINGPAIRS  A-66 
KERNINGPAIRS  data  structure  A-66 
Keyboard  control  codes  12-24 
keyboard  resources  32-18 
keyboard  statements 
keyboard  32-18 
KS_*  values  8-176,  8-188 

L 

Label  5-157, 33-18 

generate  element  for  5-157 
language  support  dialog  processing  12-83 
language  support  window  processing  12-80 
LBB_*  values  5-404,  5-462 
LCIDT_*  values  5-359 
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LCID_*  values  5-252,  5-320,  5-337,  5-443,  5-506,  5-526 
LCOLF_*  values  5-74,  5-264,  8-494 
LCOLOPT_*  5-349 

LCOLOPT_*  values  5-313,  5-333,  5-343 
LCOL_*  options  8-494 
LCOL_*  values  5-74,  5-264 
LC_*  values  5-194 
Left  cursor  key  8-547 
LHANDLE  A-66 
Line  5-159 
draw  5-159 

query  cosmetic  width  5-31 1 
query  end  5-308 
query  geometric  width  5-312 
query  join  5-309 
query  type  5-310 
query  width  5-311 
set  cosmetic  width  5-498 
set  end  5-491 
set  geometric  width  5-500 
set  join  5-493 
set  type  5-495 
set  width  5-498 
Line  at  Current  Position  33-18 
Line  at  Given  Position  33-18 
line  attribute  values  5-404,  5-462 
LINEBUNDLE  A-66 
LINEEND_*  values  5-308,  5-491 
LINEJOIN_*  values  5-309,  5-493 
LINETYPE_*  values  5-310,  5-495 
LINEWIDTHGEOM_*  values  5-312 
LINEWIDTH_*  values  5-311,  5-498 
list  box  control  data  16-1 
list  box  control  styles  16-1 
list  box  control  window  processing  16-1 
LIT_*  values  16-6 
LM_DELETEALL  16-5 
LM_DELETEITEM  16-5 
LMJNSERTITEM  16-6 
LM_QUERYITEMCOUNT  16-7 
LM_QUERYITEMHANDLE  16-7 
LM_QUERYITEMTEXT  16-8 
LM_QUERYITEMTEXTLENGTH  16-9 
LM_QUERYSELECTION  16-9 
LM_QUERYTOPINDEX  16-10 
LM_SE  ARCHSTRING  16-11 
LM_SELECTITEM  16-12 
LM_SETITEMHANDLE  16-12 
LM_SETITEMHEIGHT  16-13 
LM_SETITEMTEXT  16-14 
LM_SETTOPINDEX  16-14 
LN_*  values  16-2 
Load  Accelerator  Table  8-234 
Load  and  Process  Modal  Dialog  8-115 
Load  Bit  Map  5-161 
Load  Dialog  8-236 
Load  File  Icon  8-239 
Load  Fonts  5-163 
Load  Help  Table  8-241 
Load  Library  8-243 
Load  Menu  8-244 
Load  Message  8-246 
Load  Metafile  5-165 
Load  Pointer  8-248 
Load  Procedure  8-250 
Load  Public  Fonts  5-167 
Load  String  8-251 


load  type  options  5-193 
Loader  Hook  10-16 
LoaderHook  10-16 
LOADOPTION  32-2 
local  identifier  options  5-193 
Lock  Visible  Regions  8-253 
Lock  Window  Update  8-255 
logical  color  table 
create  5-74 
logical  font 
delete  5-106 
LONG  A-67 

LOWER_*  values  5-355,  5-541 
LSS_*  values  16-11 
LS_*  values  16-1 
LT_*  values  5-193 


M 

Make  Points  8-257 
Make  Rectangle  8-258 
Map  Dialog  Points  8-259 
Map  Window  Points  8-260 
Marker  5-168 

draw  a series  of  5-213 

draw  with  center  at  specified  position 

query  5-317 

query  box  5-318 

query  set  5-320 

query  symbol  5-317 

set  5-502 

set  box  5-504 

set  set  5-506 

Marker  at  Current  Position  33-18 
Marker  at  Given  Position  33-18 
marker  attribute  values  5-405,  5-463 
MARKERBUNDLE  A-67 
MARKSYM_*  values  5-317,  5-502 
MATRIXLF  A-68 
MBB_*  values  5-463 
MBID_*  values  8-264 
MB_*  values  8-262,  8-263 
MEMOPTION  32-2 
memory 

release  8-165 
MEMORYITEM  A-68 
menu  control  styles  17-1 
menu  control  window  processing  17-1 
menu  item  attributes  17-2 
menu  item  styles  17-2 
MENU  statement  32-11 
MENUITEM  A-68 
menus 

create  8-58 
create  window  8-58 
load  8-244 
pull-down  32-14 
templates  32-15 
message 

broadcast  8-20 
dispatch  8-113 
Message  Box  8-262 
Message  Control  Hook  10-18 
Message  Filter  Hook  10-20 
message  processing 
introduction  11-1 
notation  conventions  11-3 
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message  processing  (continued) 
types  1 1-1 
message  queues  1-2 
message  types  11-1 
messages 

create  queue  8-60 
destroy  queue  8-104 
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Query  System  Pointer  8-365 

Query  System  Value  8-368 

Query  Tag  5-363 

Query  Task  Title  8-375 

Query  Task  Window  Size  and  Position  8-373 

Query  Text  Alignment  5-364 

Query  Text  Box  5-365 

Query  the  Selected  Item  in  Listbox  8-335 

Query  Update  Rectangle  8-377 

Query  Update  Region  8-379 

Query  Version  8-381 

Query  Viewing  Limits  5-368 

Query  Viewing  Transform  Matrix  5-370 

Query  Window  8-382 

Query  Window  Device  Context  8-384 

Query  Window  Enabled  State  8-228 

Query  Window  Handle  From  Device  Context  8-572 

Query  Window  Handle  From  Identifier  8-574 

Query  Window  Long  8-398 

Query  Window  Model  8-385 

Query  Window  Pointer  8-390 

Query  Window  Pointer-Conversion  Procedure  8-397 

Query  Window  Position  8-386 

Query  Window  Process  8-388 

Query  Window  Rectangle  8-392 

Query  Window  Short  8-400 

Query  Window  Showing  8-230 

Query  Window  Text  8-394 

Query  Window  Text  Length  8-396 

Query  Window  Visibility  8-232 

Query  Workplace  Object  Handle  8-402 

QUERYRECFROMRECT  A-108 

QUERYRECFROMRECT  data  structure  A-108 

QUERYRECORDRECT  A-109 

QUERYRECORDRECT  data  structure  A-109 

queue 

query  information  8-350 

query  status  8-352 
QV_*  values  8-381 
QWL_USER  in  containers  24-1 
QWL_*  values  8-398 
QWS_*  values  8-400 
QW_*values  8-382 

R 

radio  button  13-1 

raster  fonts  5-427,  5-430,  5-433,  5-438,  5-441 , 5-445 

Realize  Palette  8-403 

RECORDCORE  A-110 

RECORDINSERT  A-111 

RECORDINSERT  data  structure  A-111 

RECORDITEM  A-111 

rectangle 
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rectangle  (continued) 
calculate  frame  8-22 
check  whether  visible  5-376 
check  whether  within  region  5-374 
compare  for  equality  8-148 
convert  to  graphic  8-258 
copy  8-39 
draw  border  8-121 
draw  interior  8-121 
exclude  from  clipping  region  5-140 
fill  8-154 
inflate  8-197 
intersect  8-205 
intersect  clip  5-155 
invalidate  8-207 
invert  8-211 

query  if  point  within  8-289 
query  update  8-377 
set  coordinates  8-489 
set  empty  8-491 
subtract  8-538 
validate  8-560 
Rectangle  In  Region  5-374 
Rectangle  Visible  5-376 
RECTDIR_*  values  A-114 
RECTL  A-112 
region 

query  box  5-345 
query  rectangles  5-347 
regions 

check  if  identical  5-134 

check  whether  point  within  5-219 

check  whether  rectangle  within  5-374 

combine  5-49 

create  5-88 

destroy  5-1 10 

frame  5-146 

invalidate  8-209 

move  5-179 

offset  5-179 

paint  5-186 

set  5-536 

validate  8-562 

Register  User  Data  Type  8-408 

Register  User  Message  8-415 

Register  User  Message  Hook  10-21 

Register  Window  Class  8-405 

Register  Workplace  Object  Class  8-407 

RegisterUserMsg  10-21 

Relative  Line  at  Current  Position  33-22 

Relative  Line  at  Given  Position  33-22 

Release  Hook  8-418 

Release  Presentation  Space  3-44,  8-420 

Remove  Dynamics  5-378 

Remove  Presentation  Parameter  8-422 

Remove  Switch  Entry  8-424 

RENDERFILE  A-112 

Replace  Workplace  Object  Class  8-426 

Request  Mutex  Semaphore  8-427 

reserved  messages  12-1 

Reset  Boundary  Data  5-381 

reset  options  5-194 

Reset  Presentation  Manager  6-17 

Reset  Presentation  Space  5-382 

resource 

load  string  from  8-251 
resource  definitions  32-2 


resource  file  specification  32-27 
resource  files 
definitions  32-2 
introduction  32-1 
source  file  specification  32-27 
syntax  definitions  32-1 
resource  script  file 
specification  32-2 
resource  script  file  specification 
keyboard  resources  32-18 
user-defined  resources  32-3 
resource  statements 
ACCELTABLE  32-9 
ASSOCTABLE  32-10 
dialog  template  32-16 
directives  32-4 
DLGTEMPLATE  32-16 
MENU  item  definition  32-13 
MENU  statement  32-11 
multiple-line  32-7 
single  line  32-2 
STRINGTABLE  32-7 
user-defined  32-3 
window  template  32-16 
WINDOWTEMPLATE  32-16 
Restore  Presentation  Space  5-384 
Restore  Window  Position  8-429 
RES_*  values  ■ 5-194 
RGB  5-77,  A-113 

RGB  (red-green-blue)  5-264,  5-343,  5-453,  8-362 
query  color  5-349 
RGB2  A-113 
RGNRECT  A-114 

RGN_*  values  5-140,  5-155,  5-345,  5-451,  8-379 

Right  cursor  key  8-547 

Roman  text  5-435 

ROP_*  values  5-24,  5-112,  5-567 

Rotate  Transform  5-386 

RRGN_*  values  5-374 

RT_*  values  32-27 

RUM_*  values  8-415 

RVIS_*  values  5-376 

s 

SAA-conforming  metafiles  5-475 

Save  Metafile  5-389 

Save  Presentation  Space  5-391 

Save  Window  Position  8-430 

SBCDATA  A-114 

SBCS  34-23 

SBMP_*  values  8-194 

SBM_QUERYPOS  20-4 

SBM_QUERYRANGE  20-4 

SBM_SETPOS  20-5 

SBM_SETSCROLLBAR  20-6 

SBM_SETTHUMBSIZE  20-7 

SBS_*  values  20-1 

SB_*  values  12-38,  12-68,  28-2,  28-5 

Scale  Matrix  5-393 

SCP_*  values  5-448 

scroll  bar  control  data  20-1 

scroll  bar  control  window  processing  20-1 

scroll  bar  styles  20-1 

Scroll  Window  8-432 

SC_*  values  15-21 

SDW_*  values  5-362,  5-546 
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SEARCHSTRING  A-115 
SEARCHSTRING  data  structure  A-115 
SEGEM_*  values  5-285,  5-480 
segment  attributes 
chained  5-539 
detectability  5-539 
highlight  5-539 
nonstore  5-539 
store  5-539 
transformability  5-539 
visibility  5-539 

Segment  Characteristics  33-22 
segments 

add  comment  5-51 
call  matrix  5-31 
close  current  5-47 
correlate  5-67 
correlate  chain  5-59 
correlate  section  of  chain  5-63 
delete  all  5-104 
delete  retained  5-102 
draw  5-123 
draw  chain  5-117 
draw  section  of  chain  5-121 
get  graphic  data  from  5-150 
open  5-181 
query  attributes  5-351 
query  initial  attributes  5-304 
query  names  5-353 
query  priority  5-355 
query  transform  matrix  5-357 
return  last  error  during  drawing  5-138 
set  attributes  5-538 
set  initial  attributes  5-488 
set  priority  5-541 
set  transform  matrix  5-543 
Select  Palette  5-396 
Send  Drag  Message  3-45 
Send  Message  8-437 
Send  Message  Hook  10-23 
Send  Message  to  Dialog  Item  8-435 
SendMsgHook  10-23 
SEPARATOR  menu  item  32-15 
session  title 
query  8-355 

Set  Accelerator  Table  8-439 

Set  Active  Window  8-441 

Set  Arc  Parameters  5-398,  33-23 

Set  Attribute  Mode  5-401 

Set  Attributes  5-404 

Set  Background  Color  5-412,  33-23 

Set  Background  Indexed  Color  33-24 

Set  Background  Mix  5-415,  33-25 

Set  Bit  Map  5-418 

Set  Bit-Map  Bits  5-420 

Set  Bit-Map  Dimension  5-423 

Set  Bit-Map  Identifier  5-425 

Set  Capture  8-442 

Set  Character  Angle  5-427,  33-26 

Set  Character  Box  5-430 

Set  Character  Break  Extra  5-433,  33-26 

Set  Character  Cell  33-27 

Set  Character  Direction  5-435,  33-28 

Set  Character  Extra  5-438,  33-28 

Set  Character  Mode  5-440 

Set  Character  Precision  33-29 

Set  Character  Set  5-443,  33-30 


Set  Character  Shear  5-445,  33-30 
Set  Checkstate  of  Button  8-30 
Set  Class  Message  Interest  8-444 
Set  Class  Pointer-Conversion  Procedure  8-447 
Set  Clip  Path  5-448,  33-31 
Set  Clip  Region  5-451 
Set  Clipboard  Data  8-449 
Set  Clipboard  Owner  8-452 
Set  Clipboard  Viewer  8-454 
Set  Code  Page  5-458,  8-456 
Set  Color  5-453,  33-31 
Set  Color  of  Text  4-26 
Set  Current  Position  5-458,  33-32 
Set  Default  Arc  Parameters  5-460 
Set  Default  Attributes  5-462 
Set  Default  Tag  5-470 
Set  Default  View  Matrix  5-467 
Set  Default  Viewing  Limits  5-472 
Set  Desktop  Background  8-457 
Set  Dialog  Item  Short  8-459 
Set  Dialog  Item  Text  8-461 
Set  Drag  Image  3-48 
Set  Draw  Control  5-474 
Set  Drawing  Mode  5-477 
Set  Edit  Mode  5-480 
Set  Element  Pointer  5-482 
Set  Element  Pointer  At  Label  5-484 
Set  Extended  Color  33-32 
Set  File  Icon  8-463 
Set  Focus  8-464 
Set  Fractional  Line  Width  33-33 
Set  Graphics  Field  5-486 
Set  Hook  8-466 
set  identifier 
delete  5-106 
Set  Indexed  Color  33-34 
Set  Individual  Attribute  33-35 
Set  Initial  Segment  Attributes  5-488 
Set  Keyboard  State  T able  8-468 
Set  Line  End  5-491,  33-36 
Set  Line  Join  5-493,  33-36 
Set  Line  Type  5-495,  33-37 
Set  Line  Width  5-498,  33-38 
Set  Line  Width  Geom  5-500 
Set  Listbox  Item  Text  8-470 
Set  Marker  5-502 
Set  Marker  Box  5-504 
Set  Marker  Cell  33-39 
Set  Marker  Precision  33-40 
Set  Marker  Set  5-506,  33-40 
Set  Marker  Symbol  33-41 
Set  Menu  Item  Text  8-472 
Set  Message  Interest  8-473 
Set  Message  Mode  8-476 
Set  Metafile  Bits  5-508 
Set  Mix  5-510,  33-41 
Set  Model  Transform  33-42 
Set  Model  Transform  Matrix  5-513 
Set  Multiple  Window  Positions  8-478 
Set  Object  Data  8-480 
Set  Owner  8-481 
Set  Page  Viewport  5-516 
Set  Palette  Entries  5-518 
Set  Parent  8-482 
Set  Pattern  5-521 

Set  Pattern  Reference  Point  5-524, 33-43 
Set  Pattern  Set  5-526,  33-44 
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Set  Pattern  Symbol  33-44 

Set  Pel  5-528 

Set  Pick  Identifier  33-45 

Set  Pick-Aperture  Position  5-530 

Set  Pick-Aperture  Size  5-531 

Set  Pointer  8-484 

Set  Pointer  Position  8-486 

Set  Pointing  Device  Pointer  3-53 

Set  Presentation  Parameter  8-487 

Set  Presentation  Space  5-533 

Set  Rectangle  8-489 

Set  Rectangle  Empty  8-491 

Set  Region  5-536 

Set  Segment  Attributes  5-538 

Set  Segment  Boundary  33-45 

Set  Segment  Priority  5-541 

Set  Segment  Transform  Matrix  5-543 

Set  Stop  Draw  5-546 

Set  Stroke  Line  Width  33-46 

Set  Synchronization  Mode  8-492 

Set  System  Colors  8-494 

Set  System  Modal  Window  8-500 

Set  System  Value  8-502 

Set  Tag  5-548 

Set  Text  Alignment  5-550,  33-47 

Set  Values  in  DRAGITEM  3-50 

Set  Viewing  Limits  5-553 

Set  Viewing  Transform  33-48 

Set  Viewing  Transform  Matrix  5-555 

Set  Viewing  Window  33-48 

Set  Window  Enabled  State  8-135 

Set  Window  Pointer-Conversion  Procedure  8-514 

Set  Window  Position  8-506 

Set  Window  Text  8-512 

Set  Window  Word  Bits  8-504 

Set  Window  Word  Long  8-515 

Set  Window  Word  Short  8-517 

Set  Window  Words  Pointer  8-510 

SF  ACTORS  A-115 

SHANDLE  A-116 

Sharp  Fillet  at  Current  Position  33-50 
Sharp  Fillet  at  Given  Position  33-50 
SHE_*  values  A-101 
SHORT  A-116 
Show  Cursor  8-518 
Show  Pointer  8-520 
Show  Tracking  Rectangle  8-522 
Show  Window  8-523 
Shutdown  System  8-525 
single-byte  character  set  1-6 
single-byte  character  sets  34-23 
SIZEF  A-116 
SIZEL  A-116 
SLDCDATA  A-116 
SLDCDAT A data  structure  A-116 
slider  control  window  processing 
data  structures  26-3 
notification  messages  26-4 
purpose  26-1 
styles  26-1 

window  messages  26-7 
SLM_ADDDETENT  26-7 
SLMQUERYDETENTPOS  26-7 
SLM_QUERYSCALETEXT  26-8 
SLM_QUERYSLIDERINFO  26-9 
SLM_QUERYTICKPOS  26-11 
SLM  QUERYTICKSIZE  26-11 


SLM_REMOVEDETENT  26-12 
SLM_SETSCALETEXT  26-13 
SLM_SETSLIDERINFO  26-13 
SLM_SETTICKSIZE  26-15 
SLS_*  values  26-1 
SMHSTRUCT  A-117 
SMIM_*  values  8-444,  8-473 
SMI_*  values  8-444,  8-473 
SM_QUERYHANDLE  22-3 
SM_SETHANDLE  22-4 
Sound  Alarm  8-11 
source  resource  file  32-27 
SPBM_OVERRIDESETLIMITS  21-3 
SPBM_QUERYLIMITS  21-4 
SPBM_QUERYVALUE  21-4 
SPBM_SET  ARRAY  21-6 
SPBM_SETCURRENTVALUE  21-6 
SPBM_SETLIMITS  21-7 
SPBM_SETMASTER  21-8 
SPBM_SETTEXTLI  M IT  21-9 
SPBM_SPINDOWN  21-9 
SPBM_SPINUP  21-10 
Specify  Text  Font  4-29 
Specify  Text  Font  Style  4-32 
spin  button  control  window  processing  21-1 
notification  message  21-2 
purpose  21-1 
styles  21-1 
SpIControlDevice  7-2 
SpICopyJob  7-5 
SpICreateDevice  7-7 
SpICreateQueue  7-10 
SpIDeleteDevice  7-14 
SpIDeleteJob  7-16 
SpIDeleteQueue  7-18 
SplEnumDevice  7-20 
SplEnumDriver  7-23 
SplEnumJob  7-26 
SplEnumPort  7-29 
SplEnumPrinter  7-32 
SplEnumQueue  7-35 
SplEnumQueueProcessor  7-39 
SPLERR  A-117 
SplHoidJob  7-42 
SplHoldQueue  7-44 
SpIPurgeQueue  7-46 
SpIQmAbort  7-48 
SpIQmAbortDoc  7-49 
SpIQmClose  7-50 
SpIQmEndDoc  7-51 
SpIQmOpen  7-53 
SpIQmStartDoc  7-55 
SpIQmWrite  7-57 
SpIQueryDevice  7-59 
SpIQueryJob  7-62 
SpIQueryQueue  7-66 
SpIReleaseJob  7-70 
SpIReleaseQueue  7-72 
SpISetDevice  7-74 
SpISetJob  7-77 
SpISetQueue  7-81 
SPL_*  values  7-51,  7-53 
Spool  File  Close  7-50 
spooler 

control  device  7-2 
copy  job  7-5 
create  device  7-7 
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spooler  (continued) 
create  queue  7-10 
delete  device  7-14 
delete  job  7-16 
delete  queue  7-18 
enumerate  device  7-20 
enumerate  driver  7-23,  7-29 
enumerate  job  7-26 
enumerate  printer  7-32 
enumerate  queue  7-35 
enumerate  queue  processor  7-39 
hold  job  7-42 
hold  queue  7-44 
purge  queue  7-46 
query  device  7-59 
query  job  7-62 
query  queue  7-66 
queue  manager  abort  7-48 
queue  manager  abort  document  7-49 
queue  manager  close  7-50 
queue  manager  end  document  7-51 
queue  manager  open  7-53 
queue  manager  start  document  7-55 
queue  manager  write  7-57 
release  job  7-70 
release  queue  7-72 
set  device  7-74 
set  job  information  7-77 
set  queue  7-81 
Spooler  Control  Device  7-2 
Spooler  Copy  Job  7-5 
Spooler  Create  Device  7-7 
Spooler  Create  Queue  7-10 
Spooler  Delete  Device  7-14 
Spooler  Delete  Job  7-16 
Spooler  Delete  Queue  7-18 
Spooler  Enumerate  Device  7-20 
Spooler  Enumerate  Driver  7-23 
Spooler  Enumerate  Job  7-26 
Spooler  Enumerate  Port  7-29 
Spooler  Enumerate  Print  Destinations  7-32 
Spooler  Enumerate  Queue  7-35 
Spooler  Enumerate  Queue  Processor  7-39 
Spooler  File  Abort  7-48 
Spooler  File  Abort  Document  7-49 
Spooler  File  End  Document  7-51 
Spooler  File  Open  7-53 
Spooler  File  Start  Document  7-55 
Spooler  File  Write  7-57 
Spooler  Hold  Job  7-42 
Spooler  Hold  Queue  7-44 
Spooler  Purge  Queue  7-46 
Spooler  Query  Device  7-59 
Spooler  Query  Job  7-62 
Spooler  Query  Queue  7-66 
Spooler  Release  Job  7-70 
Spooler  Release  Queue  7-72 
Spooler  Set  Device  7-74 
Spooler  Set  Job  7-77 
Spooler  Set  Queue  7-81 
SPTR_*  values  8-365 
SS_*  values  22-1 
standard  bit-map  formats  D-1 
Standard  File  Dialog  8-152 
Standard  File  Dialog  Default  Procedure  8-87 
Standard  Font  Dialog  8-163 
Standard  Font  Dialog  Default  Procedure  8-88 


Start  Timer  8-529 

static  control  data  22-2 

static  control  styles  22-1 

static  control  window  processing  22-1 

Stop  Timer  8-531 

storage  mapping  of  data  types  1-6 

store  attribute  for  segments 

modify  (GpiSetSegmentAttrs)  5-539 
Store  Window  Position  8-533 
string 

convert  to  uppercase  8-556 
string  handle 
create  3-5 
delete  3-10,3-11 
strings 

load  from  resource  8-251 
substitute  8-536 
STRINGTABLE  statement  32-7 
Stroke  Path  5-558 
STRUCT  A-117 
structures  A-1 
STR16  A-117 
STR32  A-117 
STR64  A-117 
STR8  A-117 
STYLECHANGE  A-117 
Subclass  Window  8-534 
submenus  32-14 
Substitute  Strings  8-536 
Subtract  Rectangle  8-538 
suppression  options  5-194 
SUP_*  values  5-194 
SV_*  values 

effect  on  container  icon  size  A-17 
effect  on  container  mini-icon  size  A-17 
SWBLOCK  A-1 18 
SWCNTRL  A-1 18 
SWENTRY  A-1 19 
Switch  To  Program  8-540 
SWL_*  values  A-1 19 
SWP  A-1 19 

SWP_*  values  8-386,  8-506,  12-69,  A-120 
SW_*  options  8-432 
SYSCLR_*  indexes  8-494 
SYSINF_*  values  8-381 
system  color 
query  8-362 
set  8-494 
system  pointer 
query  8-365 
system  value 
query  8-368 
set  8-502 


T 

tag 

query  5-363 
query  default  5-277 
set  5-548 

TA_*  values  5-550,5-551 
TBM_QUERYHILITE  23-3 
TBM_SETHILITE  23-3 
templates 

dialog  32-19 
format  32-15 
menus  32-15 
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Terminate  8-542 
Terminate  Application  8-544 
text 

draw  8-126 
query  alignment  5-364 
query  box  5-365 
set  alignment  5-550 
TF_*  values  A-121 
ThunkProc  10-3 
TID  A-120 
timer 

start  8-529 
title  bar 

control  data  23-1 
control  window  processing  23-1 
style  23-1 
TRACKINFO  A-120 
tracking  rectangle 
hide  8-522 
show  8-522 
transform  matrix 

query  model  5-325 
rotate  5-386 
scale  5-393 
set  model  5-513 
translate  5-560 

transformability  attribute  for  segments 
modify  (GpiSetSegmentAttrs)  5-539 
transforms 

set  viewing  5-555 

TRANSFORM-*  values  5-31,  5-386,  5-393,  5-467,  5-513, 
5-543,  5-555,  5-560 
Translate  Accelerator  8-550 
Translate  Character  with  Code  Page  8-40 
Translate  Matrix  5-560 
Translate  String  with  Code  Page  8-42 
TREEITEMDESC  A-122 
triplets  G-2 
TXTBOX_*  values  5-366 

u 

UCHAR  A-122 
ULONG  A-122 
Union  Rectangle  8-552 
Unload  Fonts  5-563 
Unload  Public  Fonts  5-565 
Up  cursor  key  8-547 
update  region 
exclude  8-150 
query  8-379 
Update  Window  8-554 
Uppercase  Character  8-558 
Uppercase  String  8-556 
USEITEM  A-122 
user-defined  resources  32-3 
USERBUTTON  A-122 
USHORT  A-123 


V 

Validate  Rectangle  8-560 
Validate  Region  8-562 
value  set  control  window  processing 
data  structures  27-4 
notification  messages  27-5 
purpose  27-1 


value  set  control  window  processing  (continued) 
styles  27-1 

window  messages  27-8 

Verify  Given  Rendering  Mechanism  and  Format  3-57 

Verify  Native  Rendering  Mechanism  and  Format  3-55 

Verify  True  Type  of  Dragged  Object  3-59 

Verify  Type  of  Dragged  Object  3-61 

Verify  Types  3-63 

VGA  2-19 

VIA_*  values 

querying  item  attributes  27-9 
setting  item  attributes  27-15 
view  matrix 

query  default  5-273 
viewing  limits 
query  5-368 
query  default  5-278 
set  5-553 
viewing  transform 
set  default  5-467 
viewing  transforms 
query  5-370 
VIEWITEM  A-123 
viewports 

query  page  5-330 
VIOFONTCELLSIZE  A-123 
VIOSIZECOUNT  A-123 
virtual  key  definitions  1-1 
visibility  attribute  for  segments 

modify  (GpiSetSegmentAttrs)  5-539 
VK_*  values  8-176,  A-1 
VMQUERYITEM  27-8 
VM_QUERYITEMATTR  27-9 
VM_QUERYMETRICS  27-11 
VM_QUERYSELECTEDITEM  27-12 
VM_SELECTITEM  27-12 
VM_SETITEM  27-13 
VM_SETITEMATTR  27-14 
VM_SETMETRICS  27-16 
VOID  A-123 
VSCDATA  A-123 
VSCDATA  data  structure  A-123 
VSDRAGINFO  A-123 
VSDRAGINFO  data  structure  A-123 
VSDRAGINIT  A-124 
VSTEXT  A-124 
VS_*  values  27-1 

w 

Wait  Event  Semaphore  8-565 
Wait  Message  8-567 

Wait  MuxWait  Semaphore  or  Message  8-569 

WA_*  values  8-11 

WCS_*  values  8-35 

WC_*  classes  8-398 

WC_*  values  11-2,23-1 

WinAddAtom  8-7 

WinAddSwitchEntry  8-9 

WinAlarm  8-11 

WinAssociateHelpinstance  8-13 
WinBeginEnumWindows  8-16 
WinBeginPaint  8-18 
WinBroadcastMsg  8-20 
WinCalcFrameRect  8-22 
WinCallMsgFilter  8-24 
WinCancelShutdown  8-26 
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WinChangeSwitchEntry  8-28 
WinCheckButton  8-30 
WinCheckMenultem  8-32 
WinCloseClipbrd  8-34 
WinCompareStrings  8-35 
WinCopyAccelTable  8-37 
WinCopyRect  8-39 
WinCpTranslateChar  8-40 
WinCpTranslateString  8-42 
WinCreateAccelTable  8-44 
WinCreateAtomTable  8-46 
WinCreateCursor  8-48 
WinCreateDIg  8-50 
WinCreateFrameControls  8-52 
WinCreateHelpInstance  8-54 
WinCreateHelpTable  8-56 
WinCreateMenu  8-58 
WinCreateMsgQueue  8-60 
WinCreateObject  8-62 
WinCreatePointer  8-64 
WinCreatePointerlndirect  8-66 
WinCreateStdWindow  8-68 
WinCreateSwitchEntry  8-72 
WinCreateWindow  8-74 
WinDdelnitiate  8-78 
WinDdePostMsg  8-80 
WinDdeRespond  8-83 
WinDefDIgProc  8-85 
WinDefFileDIgProc  8-87 
WinDefFontDIgProc  8-88 
WinDefWindowProc  8-89 
WinDeleteAtom  8-91 
WinDeleteLboxItem  8-93 
WinDeleteLibrary  8-95 
WinDeleteProcedure  8-96 
WinDeregisterObjectClass  8-97 
WinDestroyAccelTable  8-98 
WinDestroyAtomTable  8-99 
WinDestroyCursor  8-101 
WinDestroyHelpInstance  8-102 
WinDestroyMsgQueue  8-104 
WinDestroyObject  8-106 
WinDestroyPointer  8-107 
WinDestroyWindow  8-109 
WinDismissDIg  8-111 
WinDispatchMsg  8-113 
WinDIgBox  8-115 
window 

create  8-74 

destroy  8-109 

query  8-382 

query  active  8-293 

query  class  name  8-305 

query  desktop  8-319 

query  device  context  for  8-384 

query  handle  from  device  context  8-572 

query  pointer  8-390 

query  position  8-386 

query  size  8-386 

query  text  8-394 

query  text  length  8-396 

query  unsigned  long  integer  value  of  8-398 

query  unsigned  short  integer  value  of  8-400 

register  class  of  8-405 

scroll  8-432 

set  message  interest  8-473 
set  multiple  positions  8-478 


window  (continued) 
set  owner  8-481 
set  position  8-506 
set  to  system  modal  8-500 
update  8-554 
window  class 

set  message  interest  8-444 
window  class  styles  12-1 
Window  From  Point  8-576 
window  list 

remove  entry  8-424 
Window  List  title 
query  8-375 
Window  Procedure  10-4 
window  processing 
button  control  13-1 
combo  box  control  19-1 
container  control  24-1 
control  1 1-2 
default  11-1, 12-1 
entry  field  control  14-1 
frame  control  15-1 
language  support  12-80 
list  box  control  16-1 
menu  control  17-1 
multi-line  entry  field  control  18-1 
notebook  control  25-1 
prompted  entry  field  control  19-1 
scroll  bar  control  20-1 
slider  control  26-1 
spin  button  control  21-1 
static  control  22-1 
value  set  control  27-1 
Window  Start  Application  8-526 
windows 

create  standard  8-68 

create  standard  frame  controls  8-52 

define  procedure  10-4 

enable  update  8-137 

find  descendant  8-576 

get  maximum  position  8-179 

get  minimum  position  8-181 

get  multiples  from  identities  8-266 

invoke  default  procedure  8-89 

is  handle  valid  8-226 

map  points  8-260 

open  device  context  8-273 

process  message  box  8-262 

query  class  information  8-303 

query  descendancy  8-213 

query  enabled  state  8-228 

query  handle  from  identifier  8-574 

query  is  child  8-213 

query  object  8-340 

query  rectangle  8-392 

query  system  modal  8-364 

query  visibility  8-232 

set  active  8-441 

set  enabled  state  8-135 

set  parent  8-482 

set  text  8-512 

set  visibility  state  8-137,  8-523 
show  8-523 
start  flashing  8-158 
stop  flashing  8-158 
WINDOWTEMPLATE  statement  32-16 
WinDrawBitmap  8-118 
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WinDrawBorder  8-121 
WinDrawPointer  8-124 
WinDrawText  8-126 
WinEmptyClipbrd  8-130 
WinEnableControl  8-131 
WinEnableMenultem  8-132 
WinEnablePhysInput  8-134 
WinEnableWindow  8-135 
WinEnableWindowUpdate  8-137 
WinEndEnumWindows  8-139 
WinEndPaint  8-141 
WinEnumClipbrdFmts  8-143 
WinEnumDIgltem  8-145 
WinEnumObjectClasses  8-147 
WinEqualRect  8-148 
WinExcludeUpdateRegion  8-150 
WinFileDIg  8-152 
WinFillRect  8-154 
WinFindAtom  8-156 
WinFlashWindow  8-158 
WinFocusChange  8-160 
WinFontDIg  8-163 
WinFreeErrorlnfo  8-165 
WinFreeFileDIgList  8-166 
WinFreeFilelcon  8-168 
WinGetClipPS  8-169 
WinGetCurrentTime  8-171 
WinGetDIgMsg  8-172 
WinGetErrorlnfo  8-175 
WinGetKeyState  8-176 
WinGetLastError  8-178 
WinGetMaxPosition  8-179 
WinGetMinPosition  8-181 
WinGetMsg  8-183 
WinGetNextWindow  8-186 
WinGetPhysKeyState  8-188 
WinGetPS  8-190 
WinGetScreenPS  8-192 
WinGetSysBitmap  8-194 
WinlnflateRect  8-197 
Winlnitialize  8-199 
WinlnSendMsg  8-201 
WinlnsertLboxItem  8-203 
WinlntersectRect  8-205 
WinlnvalidateRect  8-207 
WinlnvalidateRegion  8-209 
WinlnvertRect  8-211 
WinlsChild  8-213 
WinlsControlEnabled  8-214 
WinlsMenultemChecked  8-216 
WinlsMenultemEnabled  8-218 
WinlsMenultemVaiid  8-220 
WinlsPhysInputEnabled  8-222 
WinlsRectEmpty  8-223 
WinlsThreadActive  8-224 
WinlsWindow  8-226 
WinlsWindowEnabled  8-228 
WinlsWindowShowing  8-230 
WinlsWindowVisible  8-232 
WinLoadAccelTable  8-234 
WinLoadDIg  8-236 
WinLoadFilelcon  8-239 
WinLoadHelpTable  8-241 
WinLoadLibrary  8-243 
WinLoadMenu  8-244 
WinLoadMessage  8-246 
WinLoadPointer  8-248 


WinLoadProcedure  8-250 
WinLoadString  8-251 
WinLockVisRegions  8-253 
WinLockWindowllpdate  8-255 
WinMakePoints  8-257 
WinMakeRect  8-258 
WinMapDIgPoints  8-259 
WinMapWindowPoints  8-260 
WinMessageBox  8-262 
WinMultWindowFromIDs  8-266 
WinNextChar  8-268 
WinOffsetRect  8-270 
WinOpenClipbrd  8-272 
WinOpenWindowDC  8-273 
WinPeekMsg  8-275 
WinPopupMenu  8-277 
WinPostMsg  8-281 
WinPostQueueMsg  8-283 
WinPrevChar  8-285 
WinProcessDIg  8-287 
WinPtlnRect  8-289 
WinQueryAccelTable  8-291 
WinQueryActiveWindow  8-293 
WinQueryAnchorBlock  8-294 
WinQueryAtomLength  8-295 
WinQueryAtomName  8-297 
WinQueryAtomllsage  8-299 
WinQueryButtonCheckstate  8-300 
WinQueryCapture  8-302 
WinQueryClassInfo  8-303 
WinQueryClassName  8-305 
WinQueryClassThunkProc  8-307 
WinQueryClipbrdData  8-308 
WinQueryClipbrdFmtlnfo  8-310 
WinQueryClipbrdOwner  8-312 
WinQueryClipbrdViewer  8-313 
WinQueryCp  8-314 
WinQueryCpList  8-315 
WinQueryCursorlnfo  8-316 
WinQueryDesktopBkgnd  8-317 
WinQueryDesktopWindow  8-319 
WinQueryDIgltemShort  8-321 
WinQueryDIgltemText  8-323 
WinQueryDIgltemTextLength  8-325 
WinQueryFocus  8-327 
WinQueryHelpInstance  8-328 
WinQueryLboxCount  8-330 
WinQueryLboxItemText  8-331 
WinQueryLboxItemTextLength  8-333 
WinQueryLboxSelectedltem  8-335 
WinQueryMsgPos  8-336 
WinQueryMsgTime  8-338 
WinQueryObject  8-402 
WinQueryObjectWindow  8-340 
WinQueryPointer  8-342 
WinQueryPointerlnfo  8-343 
WinQueryPointerPos  8-345 
WinQueryPresParam  8-347 
WinQueryQueuelnfo  8-350 
WinQueryQueueStatus  8-352 
WinQuerySessionTitle  8-355 
WinQuerySwitchEntry  8-357 
WinQuerySwitchHandle  8-358 
WinQuerySwitchList  8-360 
WinQuerySysColor  8-362 
WinQuerySysModalWindow  8-364 
WinQuerySysPointer  8-365 
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WinQuerySystemAtomTable  8-372 
WinQuerySysValue  8-368 
WinQueryTaskSizePos  8-373 
WinQueryTaskTitle  8-375 
WinQueryUpdateRect  8-377 
WinQueryllpdateRegion  8-379 
WinQueryVersion  8-381 
WinQueryWindow  8-382 
WinQueryWindowDC  8-384 
WinQueryWindowModel  8-385 
WinQueryWindowPos  8-386 
WinQueryWindowProcess  8-388 
WinQueryWindowPtr  8-390 
WinQueryWindowRect  8-392 
WinQueryWindowText  8-394 
WinQueryWindowTextLength  8-396 
WinQueryWindowThunkProc  8-397 
WinQueryWindowULong  8-398 
WinQueryWindowUShort  8-400 
WinRealizePalette  8-403 
WinRegisterClass  8-405 
WinRegisterObjectClass  8-407 
WinRegisterUserDatatype  8-408 
WinRegisterUserMsg  8-415 
WinReleaseHook  8-418 
WinReleasePS  8-420 
WinRemovePresParam  8-422 
WinRemoveSwitchEntry  8-424 
WinReplaceObjectClass  8-426 
WinRequestMutexSem  8-427 
WinRestoreWindowPos  8-429 
WinSaveWindowPos  8-430 
WinScrollWindow  8-432 
WinSendDIgltemMsg  8-435 
WinSendMsg  8-437 
WinSetAccelTable  8-439 
WinSetActiveWindow  8-441 
WinSetCapture  8-442 
WinSetClassMsglnterest  8-444 
WinSetClassThunkProc  8-447 
WinSetClipbrdData  8-449 
WinSetClipbrdOwner  8-452 
WinSetClipbrdViewer  8-454 
WinSetCp  8-456 
WinSetDesktopBkgnd  8-457 
WinSetDIgltemShort  8-459 
WinSetDIgltemText  8-461 
WinSetFilelcon  8-463 
WinSetFocus  8-464 
WinSetHook  8-466 
WinSetKeyboardStateTable  8-468 
WinSetLboxItemText  8-470 
WinSetMenultemText  8-472 
WinSetMsglnterest  8-473 
WinSetMsgMode  8-476 
WinSetMultWindowPos  8-478 
WinSetObjectData  8-480 
WinSetOwner  8-481 
WinSetParent  8-482 
WinSetPointer  8-484 
WinSetPointerPos  8-486 
WinSetPresParam  8-487 
WinSetRect  8-489 
WinSetRectEmpty  8-491 
WinSetSynchroMode  8-492 
WinSetSysColors  8-494 
WinSetSysModalWindow  8-500 


WinSetSysValue  8-502 

WinSetWindowBits  8-504 

WinSetWindowPos  8-506 

WinSetWindowPtr  8-510 

WinSetWindowText  8-512 

WinSetWindowThunkProc  8-514 

WinSetWindowULong  8-515 

WinSetWindowUShort  8-517 

WinShowCursor  8-518 

WinShowPointer  8-520 

WinShowTrackRect  8-522 

WinShowWindow  8-523 

WinShutdownSystem  8-525 

WinStartApp  8-526 

WinStartTimer  8-529 

WinStopTimer  8-531 

WinStoreWindowPos  8-533 

WinSubclassWindow  8-534 

WinSubstituteStrings  8-536 

WinSubtractRect  8-538 

WinSwitchToProgram  8-540 

WinTerminate  8-542 

WinTerminateApp  8-544 

WinTrackRect  8-546 

WinTranslateAccel  8-550 

WinUnionRect  8-552 

WinllpdateWindow  8-554 

WinUpper  8-556 

WinUpperChar  8-558 

WinValidateRect  8-560 

WinValidateRegion  8-562 

WinWaitEventSem  8-565 

WinWaitMsg  8-567 

WinWaitMuxWaitSem  8-569 

WinWindowFromDC  8-572 

WinWindowFromID  8-574 

WinWindowFromPoint  8-576 

WM_ACTIVATE  8-109,8-508,12-3 

WM_ACTIVATE  (in  Frame  Controls)  15-6 

WM_ACTIVATE  (Language  Support  Dialog)  12-83 

WM_ACTIVATE  (Language  Support  Window)  12-80 

WM_ADJUSTFRAMEPOS  15-6 

WMADJUSTWINDOWPOS  8-508,  12-5 

WM_APPTERMINATENOTIFY  12-4 

WM_BEGINDRAG  12-6 

WMBEGINSELECT  12-7 

WM_BUTTON1CLICK  12-7 

WM_BUTTON1 DBLCLK  12-10 

WMBUTTONI DBLCLK  (in  Frame  Controls)  15-7 

WMBUTTONI DBLCLK  (in  Multiline  Entry  Fields)  18-36 

WM  BUTTONI  DOWN  12-13 

WM_BUTTON1DOWN  (in  Frame  Controls)  15-8 

WM_BUTTON1  DOWN  (in  Multiline  Entry  Fields)  18-36 

WM~BUTTON1MOTIONEND  12-14 

WM_BUTTON1  MOTIONST  ART  12-14 

WM_BUTTON1  UP  12-19 

WM_BUTTON1UP  (in  Frame  Controls)  15-8 

WM  BUTTONI  UP  (in  Multiline  Entry  Fields)  18-37 

WMBUTTON2CLICK  12-8 

WM_BUTTON2DBLCLK  12-11 

WM_BUTTON2DBLCLK  (in  Frame  Controls)  15-7 

WM_BUTT  ON2DO  WN  12-15 

WM_BUTTON2DOWN  (in  Frame  Controls)  15-8 

WM_BUTTON2MOTIONEND  12-16 

WM_BUTTON2MOTIONST  ART  12-16 

WM_BUTTON2UP  12,20 

WM  BUTT ON2UP  (in  Frame  Controls)  15-9 
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WM_BUTT0N3CLICK  12-9 

WM_BUTT0N3DBLCLK  12-12 

WMBUTT0N3D0WN  12-17 

WMBUTT0N3M0TI0NEND  12-18 

WM_BUTT  0N3M0TI0NSTR  12-18 

WM_BUTT0N3UP  12-21 

WM_CALCFRAMERECT  12-22 

WM_CALCFRAMERECT  (in  Frame  Controls)  15-9 

WM_CALCVALIDRECTS  12-22 

WM_CHAR  12-24 

WM_CHAR  (Default  Dialogs)  12-70 

WM_CHAR  (in  Entry  Fields)  14-12 

WM_CHAR  (in  Frame  Controls)  15-9 

WM_CHAR  (in  List  Boxes)  16-15 

WM_CHAR  (in  Multiline  Entry  Fields)  18-37 

WM_CHAR  (in  Notebook  Controls)  25-18 

WM_CHAR  (in  Slider  Controls)  26-16 

WM_CHAR  (in  Value  Set  Controls)  27-17 

WM_CHORD  12-25 

WM_CLOSE  12-26 

WM_CLOSE  (Default  Dialogs)  12-71 

WM_CLOSE  (in  Frame  Controls)  15-10 

WMCOMMAND  11-3,  12-27,  15-10 

WM_COMMAND  (Default  Dialogs)  12-71 

WM_COMMAND  (in  Button  Controls)  13-3 

WM_COM M AND  (in  Menu  Controls)  17-4 

WMCONTEXTMENU  12-28 

WM_CONTROL  11-3,  12-28 

WM_CONTROL  (in  Button  Controls)  13-3 

WM_CONTROL  (in  Combination  Boxes)  19-3 

WM_CONTROL  (in  Container  Controls)  24-4 

WM_CONTROL  (in  Entry  Fields)  14-3 

WM_CONTROL  (in  List  Boxes)  16-2 

WM_CONTROL  (in  Multiline  Entry  Fields)  18-3 

WM_CONTROL  (in  Notebook  Controls)  25-3 

WM_CONTROL  (in  Slider  Controls)  26-4 

WM_CONTROL  (in  Spin  Button  Controls)  21-2 

WM_CONTROL  (in  Value  Set  Controls)  27-5 

WM_CONTROL  (Language  Support  Dialog)  12-83 

WM_CONTROL  (Language  Support  Window)  12-80 

WM_CONTROLPOINTER  12-29 

WM_CONTROLPOINTER  (in  Container  Controls)  24-5 

WM_CONTROLPOINTER  (in  Notebook  Controls)  25-19 

WM_CONTROLPOINTER  (in  Slider  Controls)  26-4 

WM_CONTROLPOINTER  (in  Value  Set  Controls)  27-6 

WM_CREATE  12-29 

WM_DDE_ACK  30-1 

WM_DDE_  ADVISE  30-2 

WM_DDE_DATA  30-3 

WM_DDE_EXECUTE  30-3 

WMDDEJNITIATE  30-5 

WM_DDE_INITIATEACK  30-5 

WM_DDE_POKE  30-6 

WM_DDE_REQUEST  30-7 

WM_DDE_TERMINATE  30-8 

WM_DDE_UNADVISE  30-9 

WM_DESTROY  8-109,  12-30 

WM_DESTROYCLIPBOARD  28-1 

WM_DRAWCLIPBOARD  28-2 

WM_DRAWITEM  12-31 

WM_DRAWITEM  (in  Container  Controls)  24-6 

WM_DRAWITEM  (in  Font  Dialog)  12-75 

WM_DRAWITEM  (in  Frame  Controls)  15-10 

WM_DRAWITEM  (in  List  Boxes)  16-3 

WM_DRAWITEM  (in  Menu  Controls)  17-4 

WM_DRAWITEM  (in  Notebook  Controls)  25-20 


WM_DRAWITEM  (in  Slider  Controls)  26-5 
WM_DRAWITEM  (in  Value  Set  Controls)  27-6 
WM_ENABLE  12-31 
WM_ENABLE  (in  Button  Controls)  13-10 
WM_ENABLE  (in  Multiline  Entry  Fields)  18-40 
WM_ENDDRAG  12-32 
WM_ENDSELECT  12-33 
WM_ERASEBACKGROUND  15-10 
WM_ERASE  WINDOW  12-33 
WM_ERROR  12-34 
WM_FLASHWINDOW  15-11 
WM_FOCUSCHANGE  12-34 
WM_FOCUSCHANGE  (in  Frame  Controls)  15-12 
WM_FORMATFRAME  12-35 
WM_FORMATFRAME  (in  Frame  Controls)  15-12 
WM_HELP  11-3,  12-36 
WM_HELP  (in  Button  Controls)  13-4 
WMJHELP  (in  Menu  Controls)  17-5 
WM_HITTEST  12-37 
WM_HSCROLL  12-38 

WM_HSCROLL  (in  Horizontal  Scroll  Bars)  20-3 
WM_HSCROLLCLIPBOARD  28-2 
WMJNITDLG  12-38 
WMJNITDLG  (Default  Dialogs)  12-71 
WMJNITMENU  12-39 
WMJNITMENU  (in  Frame  Controls)  15-13 
WMJNITMENU  (in  Menu  Controls)  17-5 
WMJOURNALNOTIFY  12-39 
WM_MATCHMNEMONIC  12-40 
WM_MATCHMNEMONIC  (Default  Dialogs)  12-71 
WM_MATCHMNEMONIC  (in  Button  Controls)  13-10 
WM_MATCHMNEMONIC  (in  Static  Controls)  22-4  . 
WMMEASUREITEM  12-41 
WM_MEASUREITEM  (in  Frame  Controls)  15-13 
WM_MEASUREITEM  (in  List  Boxes)  16-4 
WM_MEASUREITEM  (in  Menu  Controls)  17-5 
WM_MENUEND  12-41 
WM  MENUEND  (in  Menu  Controls)  17-6 
WM_MENUSELECT  12-42 
WM_MENUSELECT  (in  Frame  Controls)  15-13 
WM_MENUSELECT  (in  Menu  Controls)  17-6 
WMMINMAXFRAME  12-42 
WM_MINMAXFRAME  (in  Frame  Controls)  15-4 
WMMOUSEMOVE  12-43 

WMMOUSEMOVE  (in  Multiline  Entry  Fields)  18-40 

WMMOVE  8-508,  12-44 

WM_NEXTMENU  12-44 

WM_NEXTMENU  (in  Frame  Controls)  15-14 

WMJMEXTMENU  (in  Menu  Controls)  17-7 

WM_NULL  12-45 

WM_OPEN  12-45 

WM_OWNERPOSCHANGE  15-14 

WM_P  ACTIVATE  12-46 

WM_PAINT  12-47 

WM_PAINT  (in  Frame  Controls)  15-15 
WM_PAINT  (Langauge  Support  Window)  12-80 
WM  PAINT  (Language  Support  Dialog)  12-83 
WMPAINTCLIPBOARD  28-3 
WM_PCONTROL  12-47 
WM_PPAINT  12-48 

WM_PPAINT  (Language  Support  Dialog)  12-84 
WM_PPAINT  (Language  Support  Window)  12-81 
WM_PRESPARAMCHANGED  12-48 
WM  PRESPARAMCHANGED  (in  Container 
Controls)  24-52 

WM_PRESPARAMCHANGED  (in  Notebook 
Controls)  25-21 
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WM_PRESPARAMCHANGED  (in  Slider  Controls)  26-17 
slider  control  26-17 
value  set  control  27-18 
WM_PRESPARAMCHANGED  (in  Value  Set 
Controls)  27-18 
WM_PSETFOCUS  12-49 
WM_PSIZE  12-49 
WM_PSYSCOLORCHANGE  12-50 
WMQUERYACCELT  ABLE  12-50 
WMQUERYBORDERSIZE  15-15 
WM_QUER  Y CONVERTPOS  12-51 
WM_QUERYCONVERTPOS  (in  Button  Controls)  13-10 
WM_QUERYCONVERTPOS  (in  Entry  Fields)  14-13 
WM_QUERYCONVERTPOS  (in  Frame  Controls)  15-16 
WM_QUERYCONVERTPOS  (in  List  Boxes)  16-15 
WM_QUERY CONVERTPOS  (in  Menu  Controls)  17-23 
WM_QUERYCONVERTPOS  (in  Scroll  Bars)  20-8 
WM_QUERY CONVERTPOS  (in  Static  Controls)  22-5 
WM_QUERYCONVERTPOS  (in  Title  Bar  Controls)  23-4 
WM_QUERYDLGCODE  12-72 
WM_QUERYFOCUSCHAIN  15-16 
WMQUERYFRAMECTLCOUNT  15-17 
WM_QUERYFRAMEINFO  15-18 
WM_QUERYHELPINFO  12-52 
WM_QUERYICON  15-18 
WM_QUERYTRACKINFO  12-52 
WM_QUERYWINDOWPARAMS  12-53 
WM_QUERYWINDOWPARAMS  (in  Button 
Controls)  13-11 

WM_QUERYWINDOWP ARAMS  (in  Entry  Fields)  14-13 
WM_QUERYWINDOWP ARAMS  (in  Frame 
Controls)  15-19 

WM_QUERYWINDOWP ARAMS  (in  List  Boxes)  16-16 
WM_QUERYWINDOWP ARAMS  (in  Menu  Controls)  17-23 
WM_QUERYWINDOWP ARAMS  (in  Multiline  Entry 
Fields)  18-41 

WM_QUERYWINDOWP ARAMS  (in  Scroll  Bars)  20-8 
WM_QUERYWINDOWPARAMS  (in  Slider  Controls)  26-18 
slider  control  26-18 
value  set  control  27-19 

WM_QUERYWINDOWPARAMS  (in  Static  Controls)  22-5 
WM_QUERYWINDOWPARAMS  (in  Title  Bars)  23-4 
WM_QUERYWINDOWPARAMS  (in  Value  Set 
Controls)  27-19 
WM_QUIT  12-53 
WM_REALIZEPALETTE  12-54 
WM_RENDERALLFMTS  8-109, 28-4 
WM_RENDERFMT  28-4 
WM_SAVEAPPLICATION  12-55 
WM_SEM1  12-55 
WM_SEM2  12-56 
WM_SEM3  12-56 
WM_SEM4  12-57 
WM_SET  ACCELT  ABLE  12-57 
WM_SETBORDERSIZE  15-19 
WM_SETFOCUS  12-58 

WM_SETFOCUS  (Language  Support  Dialog)  12-84 
WM_SETFOCUS  (Language  Support  Window)  12-81 
WM_SETHELPINFO  12-58 
WM_SETICON  15-20 
WM_SETSELECTION  12-59 
WM_SETWINDOWPARAMS  12-60 
WM_SETWINDOWPARAMS  (in  Button  Controls)  13-11 
WM_SETWINDOWPARAMS  (in  Entry  Fields)  14-13 
WM_SETWINDOWP ARAMS  (in  Frame  Controls)  15-20 
WMSETWINDOWPARAMS  (in  List  Boxes)  16-16 
WM_SETWINDOWPARAMS  (in  Menu  Controls)  17-23 


WM_SETWINDOWPARAMS  (in  Multiline  Entry 
Fields)  18-42 

WM_SETWINDOWPARAMS  (in  Scroll  Bars)  20-8 
WM_SETWINDOWPARAMS  (in  Slider  Controls)  26-19 
slider  control  26-19 
value  set  control  27-20 

WM_SETWINDOWPARAMS  (in  Static  Controls)  22-5 
WM_SETWINDOWPARAMS  (in  Title  Bar  Controls)  23-4 
WM_SETWINDOWPARAMS  (in  Value  Set  Controls)  27-20 
WM_SHOW  12-60 
WMSINGLESELECT  12-61 
WM_SIZE  8-508,12-61 
WM_SIZE  (in  Frame  Controls)  15-20 
WM_SIZE  (in  Notebook  Controls)  25-22 
WM_SIZE  (in  Value  Set  Controls)  27-20 
WM_SiZE  (Language  Support  Dialog)  12-84 
WM_SIZE  (Language  Support  Window)  12-81 
WM_SIZECLIPBOARD  28-5 
WM_SUBSTITUTESTRING  12-62 
WM_SYSCOLORCHANGE  12-63 
WM_SYSCOLORCHANGE  (Language  Support 
Dialog)  12-85 

WM_SYSCOLORCHANGE  (Language  Support 
Window)  12-82 

WM_SYSCOM  M AND  1 2-63,  1 3-4,  15-21,17-7 
WM_SYSCOMMAND  (in  Title  Bar  Controls)  23-2 
WM_SYSVALUECHANGED  12-64 
WM_TEXTEDIT  12-65 
WM_TIMER  12-65 
WM_TRACKFRAME  12-66 
WM_TRACKFRAME  (in  Frame  Controls)  15-22 
WM_TRACKFRAME  (in  Title  Bar  Controls  23-2 
WM_TRANSLATEACCEL  12-67 
WM_TRANSLATEACCEL  (in  Frame  Controls)  15-23 
WM_TRANSLATEMNEMONIC  12-67 
WM_TRANSLATEMNEMONIC  (in  Frame  Controls)  15-23 
WM_UPDATEFRAME  12-68 
WM_UPDATEFRAME  (in  Frame  Controls)  15-23 
WM_VSCROLL  12-68 

WM_VSCROLL  (in  Vertical  Scroll  Bars)  20-3 
WM_VSCROLLCLIPBOARD  28-5 
WM_WINDOWPOSCHANGED  12-69 
WM_*  messages  8-352 
WNDPARAMS  A-125 
WndProc  10-4 

World  Coordinates  Bit  Bit  5-567 
wpAddClockAlarmPage  9-53 
wpAddClockDateTimePage  9-54 
wpAddClockViewl  Page  9-55 
wpAddClockView2Page  9-56 
wpAddCountryDatePage  9-57 
wpAddCountryNumbersPage  9-58 
wpAddCountryPage  9-59 
wpAddCountryTimePage  9-60 
wpAddDesktopLockupIPage  9-61 
wpAddDesktopLockup2Page  9-62 
wpAddDesktopLockup3Page  9-63 
wpAddDiskDetailsPage  9-64 
wpAddFileMenuPage  9-65 
wpAddFileTypePage  9-66 
wpAddFilelPage  9-67 
wpAddFile2Page  9-68 
wpAddFile3Page  9-69 
wpAddFolderBackgroundPage  9-70 
wpAddFolderlncludePage  9-71 
wpAddFolderSortPage  9-72 
wpAddFolderViewIPage  9-73 
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wpAddFolderView2Page  9-74 
wpAddFolderView3Page  9-75 
wpAddKeyboardMappingsPage  9-76 
wpAddKeyboardSpecialNeedsPage  9-77 
wpAddKeyboardTimingPage  9-78 
wpAddMouseMappingsPage  9-79 
wpAddMouseTimingPage  9-80 
wpAddMouseTypePage  9-81 
wpAddObjectGeneralPage  9-82 
wpAddProgramAssociationPage  9-83, 9-84 
wpAddProgramPage  9-85, 9-86 
wpAddProgramSessionPage  9-87,  9-88 
wpAddSettingsPages  9-89 
wpAddSoundWarningBeepPage  9-90 
wpAddSystemConfirmationPage  9-91 
wpAddSystemLogoPage  9-92 
wpAddSystemPrintScreenPage  9-93 
wpAddSystemWindowPage  9-94 
wpAddToObjUseList  9-95 
wpAllocMem  9-97 
WPCIock  * A-125 
wpCIose  9-98 

wpcIsCreateDefauItTemplates  9-240 
wpcIsFindObjectEnd  9-241 
wpcIsFindObjectFirst  9-242 
wpcIsFindObjectNext  9-244 
wpcIsInitData  9-246 
wpcIsMakeAwake  9-247 
wpcIsNew  9-249 
wpcIsQueryDefaultHelp  9-251 
wpcIsQueryDefauItView  9-252 
wpcIsQueryDetails  9-253 
wpcIsQueryDetailsInfo  9-254 
wpcIsQueryEditString  9-257 
wpcIsQueryError  9-258 
wpcIsQueryFolder  9-259 
wpcIsQuerylcon  9-260 
wpcIsQuerylconData  9-261 
wpcIsQuerylnstanceFilter  9-262 
wpcIsQuerylnstanceType  9-263 
wpcIsQueryObject  9-264 
wpcIsQueryOpenFolders  9-265 
wpcIsQuerySettingsPageSize  9-266 
wpcIsQueryStyle  9-267 
wpcIsQueryTitle  9-268 
wpcIsSetError  9-269 
wpcIsUnlnitData  9-270 
wpCnrlnsertObject  9-99 
wpCnrRemoveObject  9-101 
wpCnrSetEmphasis  9-102 
wpConfirmDelete  9-103 
wpCopiedFromTemplate  9-104 
wpCopy  Object  9-105 
WPCountry  * A-125 
wpCreateFromTemplate  9-106 
wpCreateShadowObject  9-107 
WPDataFile  * A-125 
wpDelete  9-108 
wpDeleteAHJobs  9-109 
wpDeleteContents  9-110 
wpDeleteFromObjUseList  9-111 
wpDeleteJob  9-112 
WPDesktop  * A-125 
WPDisk  * A-125 
wpDisplayHelp  9-113 
wpDoesObjectMatch  9-114 
wpDragCell  9-115 


wpDraggedOverObject  9-116 
wpDragOver  9-118 
wpDrop  9-119 
wpOroppedOnObject  9-120 
wpEditCell  9-121 
wpEndConversation  9-122 
WPFileSystem  * A-125 
wpFilterPopupMenu  9-123 
wpFindUseltem  9-125 
WPFolder  * A-125 
wpFormatDragltem  9-126 
wpFree  9-127 
wpFreeMem  9-128 
wpHide  9-129 
wpHideFIdrRunObjs  9-130 
wpHoIdJob  9-131 
wpHoldPrinter  9-132 
wpInitData  9-133 
wpInsertPopupMenultems  9-134 
wpInsertSettingsPage  9-136 
wpIsCurrentDesktop  9-137 
WPJob  * A-126 
WPKeyboard  * A-126 
wpMenultemHelpSelected  9-138 
wpMenultemSelected  9-139 
wpModifyPopupMenu  9-140 
WPMouse  * A-126 
wpMoveObject  9-141 
WPM_*  values  A-125 
WPObject  * A-126 
WPOINT  A-126 
wpOpen  9-142 
wpPaintCell  9-143 
WPPalette  * A-126 
wpPopulate  9-144 
WPPrinter  * A-126 
wpPrintJobNext  9-145 
wpPrintMetaFile  9-146 
wpPrintObject  9-147 
wpPrintPifFile  9-148 
wpPrintPlainTextFile  9-149 
wpPrintPrinterSpecificFile  9-150 
wpPrintUnknownFile  9-151 
WPProgramFile  * A-126 
WPProgramGroup  * A-126 
WPProgram  * A-126 
wpQueryAssociationFilter  9-152, 9-153 
wpQueryAssociationType  9-154,  9-155 
wpQueryComputerName  9-156 
wpQueryConfirmations  9-157 
wpQueryContent  9-158 
wpQueryDefaultHelp  9-159 
wpQueryDefauItView  9-160 
wpQueryDetailsData  9-161 
wpQuery Error  9-163 
wpQueryFIdrAttr  9-164 
wpQueryFIdrOetailsClass  9-165 
wpQueryFIdrFlags  9-166 
wpQueryFIdrFont  9-167 
wpQueryHandle  9-168 
wpQuery  Icon  9-169 
wpQuerylconData  9-170 
wpQueryLogicalDrive  9-171 
wpQueryNextlconPos  9-172 
wpQueryPaletteHelp  9-173 
wpQueryPalettelnto  9-174 
wpQueryPrinterName  9-175 
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wpQueryProgDetails  9-176, 9-177  «. 

wpQueryRealName  9-178  A 

wpQueryRootFolder  9-179  XYF_*  values  A-128 

wpQueryShadowedObject  9-180  XYWINSIZE  A-127 

wpQueryStyle  9-181 

wpQueryTitle  9-182 

wpQueryType  9-183 

wpRedrawCell  9-184 

wpRefresh  9-185 

wpRegisterView  9-186 

wpReleaseJob  9-187 

wpReleasePrinter  9-188 

wpRender  9-189 

wpRenderComplete  9-190 

wpRestore  9-191 

wpRestoreData  9-192 

wpRestoreLong  9-193 

wpRestoreState  9-194 

wpRestoreString  9-195 

WPRootFolder  * A-126 

wpSaveData  9-196 

wpSaveDeferred  9-197 

wpSavelmmediate  9-198 

wpSaveLong  9-199 

wpSaveState  9-200 

wpSaveString  9-201 

wpScanSetupString  9-202 

wpSetAssociationFllter  9-204,  9-205 

wpSetAssociationType  9-206, 9-207 

wpSetComputerName  9-208 

wpSetDefaultHelp  9-209 

wpSetDefaultPrinter  9-210 

wpSetDefauItView  9-211 

wpSetError  9-212 

wpSetFIdrAttr  9-213 

wpSetFIdrDetailsClass  9-214 

wpSetFIdrFlags  9-215 

wpSetFIdrFont  9-216 

wpSetlcon  9-217 

wpSetlconData  9-218 

wpSetNextlconPos  9-219 

wpSetPalettelnfo  9-220 

wpSetPrinterName  9-221 

wpSetProgOetails  9-222, 9-223 

wpSetRealName  9-224 

wpSetShadowTitle  9-225 

wpSetStyle  9-226 

wpSetTitle  9-227 

wpSetType  9-228 

wpSetup  9-229 

wpSetupCell  9-233 

WPShadow  * A-126 

wpShowPalettePointer  9-234 

WPSound  * A-126 

WPSpooler  * A-126 

WPSRCLASSBLOCK*  A-126 

wpStartJobAgain  9-235 

wpSwitchTo  9-236 

WPSystem  * A-127 

wpUnlnitData  9-238 

wpUnlockObject  9-237 

WRECT  A-127 

Write  Profile  Data  6-19 

Write  Profile  String  6-21 

WS_*  values  8-190,  12-2 
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